Update on migration in Drupal 8

It's been a breathless past several weeks in Migrateland - with the core committers as a whole focused on trimming the criticals list for Drupal 8 to zero, Angie "webchick" Byron has given quality time to help the Migrate team get unblocked, triggering a flurry of activity. All along I've meant to post a status update, but things have been moving so fast it's been "well, after this next commit..." Let's review where we stand at the moment, as of September 18, 2015.

Upgrade path

From the initial decision to replace the traditional update-in-place (update.php) approach to major version upgrades with a migration-based (import into a fresh site) approach, it was made clear that the initial Drupal 8 release would not be blocked on the upgrade path. If the upgrade path was not "ready", Drupal 8.0.0 would release without it and be available for building new sites only. The plan was as Drupal 8 approached RC status the decision would be made over migration support in 8.0.0. That decision has been reached and published. By all means go ahead and read the official policy as well, but tl;dr: the migrate API and the Drupal 6 upgrade path (and possibly the Drupal 7 upgrade path as well) should be part of the Drupal 8.0.0 release, but marked as "Experimental". Why "Experimental"? Although the Drupal 6 upgrade path (the #1 priority, given that Drupal 6 support goes away 3 months after Drupal 8 is released) has been stable for some time, there is a huge variety of existing Drupal 6 sites out there, and the migration path has not yet been tested with a wide selection of those. While what we've implemented so far should work with perfectly clean, normal Drupal 6 sites, after seven and a half years many sites have drifted far from "clean" and "normal". The expectation that would come with full support in 8.0.0 - that all Drupal 6 sites would migrate to Drupal 8 smoothly - isn't supportable; there are most certainly plenty of sites out there that won't make the transition cleanly, and we need more time (and most importantly, more sites upgraded) to be confident that the migration path will work most of the time, and help give you the information you need to bridge any gaps. So, for the 8.0.0 time frame, consider the Drupal 6 support to be a clinical trial - it should work most of the time, but buyer beware. As for the Drupal 7 upgrade path, at this point we've got the major pieces of the puzzle in - users, nodes, terms, comments, blocks. There are still a number of smaller bits to go - various pieces of configuration, less-central modules such as Tracker, etc. - but we expect to have the Drupal 7 upgrade path complete (if not necessarily as well-exercised as Drupal 6) by the 8.0.0 release.

Upgrade UI

Now, above, I've spoken of the infrastructure that supports Drupal 6 and 7 upgrades to Drupal 8 - but how do you actually perform the upgrade? A UI and drush command for performing straight upgades is now available as the contrib module migrate_upgrade. The UI being developed here will be incorporated into core itself - our goal is to get the usability and accessibility to a sufficient level of quality to get it into core for the Drupal 8 RC1 (marked Experimental, as with the infrastructure above). The drush command should be submitted to be a core part of drush itself - we don't have a firm timeline for that, but since it shares code with the UI this would happen after the UI goes into core (with that shared code) so the command can leverage it. I will have a follow-up blog post to discuss the UI in particular in more detail.

What's left to do?

  1. Get the UI ready for incorporation into the D8 RC.
  2. Finish the Drupal 7 migrations.
  3. Clean up a few API and testing issues.
  4. Complete the documentation.

How can I help?

  1. Anyone with an existing Drupal 6 or Drupal 7 site - test the upgrade path. Report any bugs you find, or general feedback on the process in the drupal.org issue queues.
  2. Developers - submit patches for problems you find. And especially front-end developers - please help refine the UI (I've done most of that work to date, but I'm a back-end developer flailing as best I can - I know you can do in an hour what takes me 5!).


In recent months, Adam "phenaproxima" Hoenich has made the most contributions of anyone to the Drupal 8 migration system. Also providing substantial help in the recent surge have been neclimdul, quietone, lostkangaroo, benjy - apologies to anyone I've missed...



Is there a documentation page that explains, to module maintainers, what they need to do to build migration functionality into their module?

Not really, yet - https://www.drupal.org/node/2127611 is the root of the Migrate API documentation, and as I said above completing the documentation (https://www.drupal.org/node/2561243) is on the to-do list. Right now, as a contrib author, my best suggestion is to look at how core modules do it - contrib won't be any different. Pick a core module such as user, and look at the migration_templates directory for examples of configuring the migration process and src/Plugin/migrate for how to implement plugins you might need.