Migrate UI - allow modules to declare their migration status

Problem/Motivation

Modules need a way to declare their migration status and give a short description on the Migrate Upgrade review page, /upgrade. The short description can have a link to a documentation page for example for known issues.

The form lists all modules on the source site in either a 'will be upgraded' or 'will not be upgraded' list. If the module has migrations, it will be displayed in the 'will be upgraded' list, even if it only has one migration and needs more than one to be complete. We need a mechanism that can explain this situation in the UI.

Note: in #2914974: Migrate UI - handle sources that do not need an upgrade we defined a list of modules that do not need any migrations (e.g. Overlay, Help) or the contrib functionality has moved into core and there is not a D8 core module with the same name. These modules are listed in ReviewForm::$noUpgradePaths

In a migrate meeting, using a hook or an event was discussed. A possible solution, using hook_form_alter, was implemented in #2914974: Migrate UI - handle sources that do not need an upgrade and removed after a review #176. That review asked some questions, listed below, which should be resolved here.

1. The CR is titled Provide a Method to Intentionally Mark Modules, Themes and Profiles as not Upgradable but we're not really providing a method.
2. Did we give consideration to a dedicated API? E.g. we could put entries in .info.yml or we could put .migrate.info.yml files in modules.
3. How likely is it that contrib modules will need to make this change?

Proposed resolution

Add the following to info.yml to any module providing or needing migrations, include field migrations.

migrations_finished:
  6:
    source_module_A: destination_module_A
    source_module_A: destination_module_B
  7:
    source_module_A: destination_module_A
    source_module_B: destination_module_B
migrations_not_finished:
  6:
    source_module_C: destination_module_D

In 'migrations_finished' is a list of all source module/destination module pairs for migrations that are complete in the module. If migrations are found in the module it will be assumed that the migrations are not finished. The 'migrations_not_finished' is needed when more than one module will contain migrations for a source module and at least one of the modules uses the 'migrations_finished' key. Say Module A and Module B provide migrations for Module C. Module A is finished and uses 'migrations_finished'. Then, if Module B has no migrations, it needs to use 'migrations_not_finished'.

See the full details in #72and #77

Screen shots

Now, for the screen shots which need some attention. The difference between the before and after is that on the after screenshots the modules in the Drupal 8 column are listed in a single line separated by commas whereas in the before screenshots they are on separate lines. That's all.

But the screens should provide some information or direction to the user on what to do about the modules in the 'will not be upgraded' section. After all, if a module they need is listed here they need a next step right on this page. How best to inform them of what to do? A single help text somewhere on the page or something else? The user also needs support on what to do about the other modules that will not be upgraded. See #87

Also, the idea of allowing modules to add text to the page via a hook, in a possible followup, has been discussed by the team. Any decision here should be aware of that.

To navigate to the Review page you need a D6 or D7 Database Then install Migrate Drupal UI and go to /upgrade.

Before
Full page
Module that will not be upgraded section
Modules that will be upgraded

After
Modules that will not be upgraded section
Modules that will be upgraded section

History

The first proposal which came from a migrate meeting was to add the migrate status of the module and a description string to be displayed on the Review Page to info.yml . This was tweaked a few times. See #7 and #8. See #10. Eventually, the description was removed as to difficult to maintain an html string in .info but the version key remained.

Remaining tasks

• Decide on the format of the new 'migrate' key and values in .info.yml. Suggested formats are in #11 and #15. Those have been abandoned in favor of 'migrations_finished' and 'migrations_not_finished'.
• Decide on the allowed values for status. Suggestions are in #7, #9. Currently proposed values are 'complete', 'incomplete' and 'n/a'. The UI impact with a screenshot is in #28.
• Decide if adding a key for source version is ok.As pointed out in #10, the status needs to be declared by source version.
• Review
• UX Review
• Update change record
• Update handbook documentation
• Commit