Migration issues

From PKP Wiki
Jump to: navigation, search

To help integrate the new features of OMP into our other applications, we'll describe in this document how we've modified OMP to make it easier in the future to backport.

Every change should be accompanied by the following information:

  • Link to the original BugZilla entry
  • Link to an exemplary migration example patch (within BugZilla)
  • A rough estimate of the number of instances that have to be migrated across all apps
  • A rough estimate of the time required to migrate one instance

Introduction of Routers (Florian)

  • The request class contained methods like getRequestedPage() and getRequestedOperation() which were specific to page request and not compatible with AJAX or more generally sub-component requests.
  • We therefore introduced a distinction between the request containing URL and request parameters and routers that pass control to a handler operation based on the request information.
  • A dispatcher is now responsible to choose an appropriate router for the request and let it route the request to a handler endpoint.
  • We also want to reduce the number of static function calls which have been very frequent in connection with the Request class (advantages: enable inheritance, compatibility problems, design advantages). We now pass a request object along the execution chain, passing by the dispatcher and the router into the handler operation. All handler operations now receive the request as a second argument to their method call.
  • The original BugZilla entry is http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=4934
  • A sample migration patches can be found here:
  • There are currently 400 files which have non-migrated instances of 'Request::'.
  • The migration of one file should take between 5 minutes and 15 minutes per instance, depending on the number of occurrences.
  • This means that the overall migration effort should be roughly 60 hours.

Replacing HandlerValidators with AuthorizationPolicies (Florian)

  • For a rationale why we replaced handler validators with authorization policies see our [Authorization Framework] design document.
  • The original BugZilla entry is http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=5540. The migration itself has been posted as http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=5868 which also contains a set of sample migration patches.
  • All instances of HandlerValidators have already been replaced there are however still a large number of validate() methods that contain custom authorization code which must be converted into AuthorizationPolicies.
  • There are currently about 70 instances of the validate() method.
  • There are still compatibility classes for the deprecated HandlerValidator classes which must be removed.
  • The migration of one method takes about 10 to 15 minutes, if a new policy must be written first (which will occur quite rarely once the first few files have been migrated) then we have to count another 15 minutes per policy. Removing the legacy handler validators takes not more than 10 minutes.
  • The overall migration effort therefore should be roughly 15-20 hours.

Layout overhaul (Bruno, Brent, Juan, Matt)

Changes for OMP: [1]

  • Various locale keys have been added for navigation text (see the changes in the github commit)
  • Added 'Select Role' and 'Select Press' block plugins
  • Added omp/styles/omp.css file which contains references to all CSS files used. This file is the only CSS file needed to be referenced in omp/templates/common/header.tpl. The existing CSS files have been modified (see the changes on github)
  • All javascript is being called in /templates/common/header.tpl. This means that the jQuery plugin is no longer in use. In the future we will be using Google's CDN to call jQuery and jQueryUI, and eventually other libraries.
  • New container divs have been added to header.tpl, and leftSidebar/rightSidebar code has been removed. (see the changes on github for exactly what to change)
  • A new breadcrumb file has been added in omp/templates/common/breadcrumbs.tpl--This should be able to be copied directly over (or eventually abstracted into pkp-lib)
  • /omp/templates/common/footer.tpl was added to include closing tags for new divs added to header.tpl. When all of the application's UIs are in sync, this can be abstracted to pkp-lib.

Changes for PKP-lib: [2]

  • Various CSS and Javascript libraries have been added to allow for new UI features, as well as new images
  • original bug reports: tbd.
  • sample migration patches: tbd.
  • migration effort: tbd.

Listbuilders (Florian, Matt, Michael)

For form elements that involve simple manipulation of lists (like masthead user lists in all apps), the MVC structure of modifying this data can be compacted into a listbuilder handler located in controllers/listbuilder/. There are three source data types of listbuilders that can be used, here are some examples:

  • Free-text entry (for adding new data to the system)--See /controllers/listbuilder/AuthorRolesListbuilderHandler.inc.php
  • Drop-down list selection (for adding already-existing data to a new group or classification)--See /controllers/listbuilder/InternalReviewRolesListbuilderHandler.inc.php
  • Autosuggest selection (Like drop-down list selection, but typically for larger data sets such as users)--See /controllers/listbuilder/MastheadMembershipListbuilderHandler.inc.php
  • original bug reports: tbd.
  • sample migration patches: tbd.
  • migration effort: tbd.

Form Builder Vocabulary (Tyler)

See: Form Builder Vocabulary

  • original bug reports: tbd.
  • sample migration patches: tbd.
  • migration effort: tbd.

Introduction of User Groups (Juan, Florian)

  • change in the data model
  • introduction of "acting as user group" in the session

Process-based (rather than role-based) workflow pages (Florian, Juan)

  • description: Rather than using role based URLs for the editorial workflow we now have a /workflow handler that introduces a process based view on editorial workflow. This logic needs to be ported to OJS/OCS for consistency.
  • original bug report(s): tbd
  • sample patch: tbd
  • migration effort: tbd

Introduction of a dashboard for users (Juan, Matt, Florian)

  • description: We'll introduce a common entry point for users. Among other things this contains a submission list which will be common to all roles and change depending on the "acting-as" user group.
  • original bug report(s): http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=5807, http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=5802
  • sample patch: This is a large change with an individual change set per application. Therefore a sample patch cannot be provided.
  • migration effort: tbd.

Converting edit assignments to stage assignments (Matt)

  • description: OMP uses stage assignments (through the Signoff table) to enable users to access submissions. Each user can access pages and components that are registered against a particular stage, and which they have been given access to (via automatic assignment or by the editor assigning them from the stage assignment grid, which lives at the top of the submission details page):
    • All uses of the edit assignments classes need be replaced.
    • The g/setEditAssignments functions in each role submission class (authorSubmission, editorSubmission) needs to be removed (TBD if shortcut functions to the stage assignments should be in there)
    • The getAssociatedUserIds() function needs to be reimplemented to work with user groups and stage assignments
  • original bug report(s): http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=5557
  • sample patch: tbd.
  • migration effort: tbd.

Introduction of a new review concept (Matt, Juan, Alec)

  • description: OMP works with a "review round" concept (see ReviewRound class) that's not used in OJS/OCS. Conceptually the review of OMP and OJS/OCS are not so different to justify such a difference in the long run, though. Also the review rounds need clean-up in both OMP and the other apps.
  • original bug report(s): tbd., 6406 (clean-up only)
  • sample patch: tbd.
  • migration effort: tbd.

File management (Matt, Florian)

  • description: The file data model and file handling has been re-designed for OMP:
    • The file data model has been cleaned up (somewhat) in OMP although the file data model can probably still be considerably simplified (see #6410 for some issues).
    • The OMP file implementation has an additional notion of "file genre" that doesn't exist in OJS/OCS. We have to decide whether we use this in OxS or factor it out as OMP-specific before migrating to OJS/OCS.
    • The OMP review files assignment work differently from the other apps.
    • OMP uses file stages and file ids differently than the other apps. Most notably, OMP allows more than one file per file stage/role and submission while OxS use the notion of separate supplementary files instead which do not exist in OMP because all files are treated the same.
    • OMP assigns review files differently than the other apps.
    • File management is now completely done in grids.

We have to identify all places where files are being managed in the other applications and introduce the file handling grids and data model there.

  • original bug report(s): 5620, 6125, 6127, 6128, 6410
  • sample patch: this change is too complex to provide a patch that can be cross-applied
  • migration effort: the effort depends on the number of places where files are being used. This is much higher in OCS/OJS than in OHS. I guess the effort is somewhere between three days and two weeks for each of OJS/OCS because the whole file class hierarchy needs to be replaced and file handling grids to be written and inserted. A lot of file handling code should be re-usable from OMP, though as the rewrite has been made with migration in mind.

JavaScript Framework (Florian)

  • description: Procedural JavaScript, especially JS in template files needs to be factored into wizard controllers or JS helper objects according to the rules of the JS framework for better maintainability and re-use.
  • original bug report(s): 6294
  • sample patch: see the commits in #6294. Also take a look at existing handlers and the JS framework documentation on the Wiki, the initial reference implementation was the OMP file upload form.
  • migration effort: small pieces of JS in a template should not take longer than 2 hours per instance to clean up (including tests), if existing code can be re-used then one migration can take less than five minutes. Very roughly estimated we've got about 300 migratable pieces of script in OJS much of which is duplicate code (so no new handlers required for all of them of course). I guess that we need to write max. 50 handler hierarchies or so which can then be re-used across apps. This will be considerably less once we migrate the UI which also introduces a lot of standardization on the UI side and will reduce the handlers overall to variations of max. 30 basic UI widgets with controllers attached.

DAO clean-up (Florian)

  • description: We do not have a consistent or clean design for DAOs that map OO inheritance hierarchies to database entities. Clean design options have been specified in the Wiki and a reference implementation (submission files) exists in OMP.
  • original bug report(s): 6127, 6185
  • sample patch: see the change sets linked in the linked bug report
  • migration effort: I so far identified the following class hierarchies as candidates for a re-factoring:
    • submissions: this would be a huge re-factoring and we should probably go about it in small feasible steps, it would be great to have a target design developed and available, though, to direct our changes even when on a small scale
    • submission files (including configuration files and galleys): see the re-factoring in OMP, this needs to be ported to other apps. I guess: 2-3 weeks full time for OJS and OCS, 2 days for OHS

CSS / phpless (Alec)

  • description: We divide CSS into smaller files that contain well defined CSS for specific components. This system needs to be ported over to OxS.
  • original bug report(s): tbd.
  • sample patch: tbd.
  • migration effort: tbd.