Migrate UI - allow modules to declare the state of their migrations

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 Review form lists all modules on the source site in either a 'will be upgraded' or 'will not be upgraded' list. However, determining which section to add a module too is not robust. 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.

The mechanism needs to be flexible to accommodate the many scenarios possible. See #71 and #72 for details.

This work here is to only create and implement such a system, to make the first step, for what is a complicated problem. Changes may be made to the UI but are expected to be minimal. However, a UX review is planned. When that feedback is given it needs to be decided what can be done in this issue and what must be moved to followups.

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

Allow Drupal 8 modules to declare their migration state in module_name.migrate_drupal.yml. This will allow the Review form (at /upgrade) to display accurate information. See Change Record for details and usage examples.

A brief description:
In 'finished' is a list of all source module/destination module pairs for migrations that are complete in the module. In 'not_finished' is a list of all the migrations this module intends to provide but either do not exist or are incomplete for any reason. Any migrations discovered in the module that do not have a corresponding entry in the migrate_drupal.yml file will be assumed 'not finished'.

The 'not_finished' is needed because more than one module can have migrations for a source module and at least one of the modules uses the 'finished' key. The 'not_finished' one will ensure that the source module is listed in the 'will not be upgraded' list. Say Module A and Module B provide migrations for Module C. Module A is finished and uses 'finished'. Then, if Module B has no migrations, it needs to use 'not_finished'.

Screen shots

The difference between the before and after is that on the after screenshots the modules in the Drupal 8 column will be listed in a single line separated by commas whereas in the before screenshots they are on separate lines. That's all.

The new Review page also has a new help text string to give some information or direction to the user on what to do about the modules in the 'will not be upgraded' section. The new help text is

The new site is missing modules corresponding to the old site's modules. Unless they are installed prior to the upgrade, configuration and/or content needed by them will not be available on your new site. Read the checklist to help decide what to do.", [':review' => 'https://www.drupal.org/docs/8/upgrade/upgrade-using-web-browser#pre-upgr...']),

See #87

Screens shots using the Drupal 6 Ubercart test database from Commerce Migrate.
Before
Module that will not be upgraded section

After
Modules that will not be upgraded section

Screens shots using the Drupal 6 test fixture.
Before
Modules that will be upgraded

After
Modules that will be upgraded
The checklist referred to is https://www.drupal.org/docs/8/upgrade/upgrade-using-web-browser#pre-upgr...

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.

After framework manager review the status information moved from .info.yml to module.migrate.yml, the format stays the same. And later it moved to migrate_drupal.yml since this is only for drupal sources. See comment #124.

All the logic to determine whether a source module will be upgraded or not is now in a service (See suggestion in #137.9, migrate_drupal.migration_state.

Discussion of the logic are in #72 and #77

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 - See #106 - #11
• Update change record</li>
• Update handbook documentation
• Commit
• Possible followup: Allow modules to add text to the page via a hook.