The Migrate Drupal UI module provides a web browser user interface for upgrading from Drupal 6 / 7 to Drupal 8. There is a pre-upgrade analysis which displays a list of legacy modules that will be upgraded and will not be upgraded. Included in those that will be upgraded are modules that do not need an upgrade, such as the Help module. In order for this analysis to be correct, some Drupal 8 modules must provide information in a MODULE_NAME.migrate_drupal.yml file in the module's migrations/state directory.
This applies to Drupal 8 modules that:
- Provide migrations from a Drupal 6 or Drupal 7 module, or
- Intend to provide those migrations in the future, or
- Are a successor to a Drupal 6 or Drupal 7 module and want to communicate that no migration is needed.
This does not apply to modules that are brand new in Drupal 8 and have nothing to communicate about any Drupal 6 or Drupal 7 modules.
Syntax
finished:
6:
source_module: destination_module
source_module_2: destination_module
source_module_3:
- destination_module
- destination_module_2
7:
source_module: destination_module
source_module_3:
- destination_module
- destination_module_2
not_finished:
7:
source_module_2: destination_module
As can be seen above, the data in migrations/state/MODULE_NAME.migrate_drupal.yml consists of migration sets where each set is a source module for a legacy Drupal version (6 or 7), and one or more destination modules for the current Drupal version (8). The source module and destination modules correspond to the source_module and destination_module definitions in the migrations. And each set can be declared either 'finished' or 'not_finished'. For a set to be "finished", all of the migrations for the set must exist. If a module maintainer knows that they have not yet provided all of the migrations that are needed from a given source module to one or more destination modules, then they should declare that set as "not_finished".
Merging state across provider modules, source modules, and destination modules
Each module's migrations/state/MODULE_NAME.migrate_drupal.yml file defines the state of the migrations that are provided (or intended to be provided in the future) by that module. In most cases, destination modules are the sole providers of migrations to themselves. For example, the dblog module is the sole module that provides migrations from earlier versions of itself to itself. In some cases, modules provide migrations for other destination modules. For example, the Content Translation module provides migrations from earlier versions of the Statistics module to the current version of the Statistics module. This is in addition to the migrations provided by the Statistics module itself.
The Migrate Drupal module considers a source module / destination module pair as not finished if there is any provider that declares it as not finished. For example, in the above example, if the Content Translation module in its .migrate_drupal.yml were to declare that statistics: statistics were "not_finished", then Migrate Drupal considers that pair to be not finished, even if the Statistics module itself is finished with the migrations that it intends to provide.
Similarly, a given source module is considered not finished overall, if there exists at least one destination module for which it is declared as not finished. For example, there are migrations from the Drupal 6/7 Menu module to several Drupal 8 destination modules (System, Menu UI, and Custom Menu Links). If any one of those pairs (e.g., menu: system, menu: menu_ui, or menu: menu_link_content) were declared as not finished (by any provider module), then on the Migrate Drupal UI pre-upgrade review screen, the Menu module would be listed as "will not be upgraded".
Usage
If the Drupal 8 module is not providing migrations, now or in the future, for its legacy version then create a migrate_drupal.yml. Declare a finished migration for each legacy Drupal version. See scenario 1 below.
If the Drupal 8 module is or will be providing migrations for a legacy module then create a migrate_drupal.yml file. For each source_module:destination_module pair used by the migrations in your module do the following for Drupal 6 and Drupal 7.
- If the migrations for the pair are complete add a line in the "finished" array for the relevant Drupal version.
- If at least one migration for a pair exists but the pair is not finished add an entry to "not_finished" for the relevant Drupal version.
- If the migrations needed for the pair do not exist then add a line in the "not_finished" array for the relevant Drupal versions.
Examples
Scenario 1. A successor to a legacy module that for any reason will not be providing a migration. Let's use Pirate as the example. Currently, if Pirate is enabled on the legacy site it will be displayed as will not be upgraded when it should be listed as will be upgraded. To make that happen simply declare a migration set with pirate as the source module and destination module as finished.
finished:
6:
pirate: pirate
7:
pirate: pirate
Scenario 2. The legacy version of your module has content and configuration that needs to be upgraded. Your module provides two migrations with the same source_module:destination_module pair for both Drupal 6 and Drupal 7 and all migrations are finished.
finished:
6:
google_analytics: google_analytics
7:
google_analytics: google_analytics
Scenario 3. Your module provides migrations. The Drupal 6 version is complete but the Drupal 7 is not. Note there may be zero or more migrations for Drupal 7 in your module but more are needed for it to be complete.
finished:
6:
google_analytics: google_analytics
not_finished:
7:
google_analytics: google_analytics
Scenario 4. Your module provides migrations for other modules with many pairs, such as Commerce Migrate Module.
finished:
6:
node: commerce_product
system: commerce_store
7:
node: commerce_product
commerce_product: commerce_product
system: commerce_store
not_finished:
6:
uc_orders: commerce_order
7:
uc_orders: commerce_order
commerce_order: commerce_order
Scenario 5. Your module provides a migrate field plugin for a legacy field, such as Address Module.
finished:
6:
adressfield: address
7:
adressfield: address
Scenario 6. Menu, JQuery UI, Blog, Color and many other modules moved directly into Core. These are denoted as 'core' for the destination and are treated specially. They are marked as finished since these do not have an upgrade path and site upgraders do not need to look for an equivalent project to install in Drupal 8.
finished:
6:
blog: core
blogapi: core
calendarsignup: core
color: color
7:
blog: core
bulk_export: core
contextual: core
ctools: core
