Migrations manual

The core "Migrate Drupal" module in Drupal 8 provides API support for migrating from Drupal to Drupal, and the "Migrate Drupal UI" module offers a simple user interface for upgrading from older versions of Drupal.

Upgrades from Drupal 6 to Drupal 8 and Drupal 7 to Drupal 8 are stable for monolingual sites. The upgrade path for multilingual sites is not yet complete. Refer to Upgrading multilingual Drupal 6 to Drupal 8 for an overview, and the multilingual migration meta issue for a list of related issues. There are several ways to ensure stable D6-D8 and D7-D8 upgrade paths.

Thoroughly test your site's upgrade and report your findings

When upgrading your Drupal 6 or Drupal 7 site to Drupal 8, be sure to test thoroughly and verify your results. You may discover something that did not upgrade as expected. When this happens:

• First check if the issue is listed in Known issues when upgrading from Drupal 6 or 7 to Drupal 8.
• If your issue is not listed, look for open issues for Drupal 6 - Drupal 8 migration or Drupal 7 - Drupal 8 migration issues.
• If no existing issue matches yours, please create a new issue in the core migration system queue. Reporting a migration bug is a valuable contribution and helps improve migration stability!

New issues should be filed under the "migration system" component. Provide as much and as detailed information as possible:

• Include screenshots of before (from Drupal 6/7) and after (Drupal 8) where applicable.
• Describe the issue clearly and specifically.
• Mention any site details you believe might be relevant to the issue.
• Example of a good issue report: https://www.drupal.org/node/2853872

                        - Summary, screenshot, and labels were provided in the original issue report.
                        - The issue summary was updated multiple times as more information emerged.
                        - Keeping the issue summary up-to-date is crucial. Migrating bugs can be complex and timely updates help maintainers and contributors a lot!
                        - Don’t hesitate – we appreciate detailed bug reports!

Help test patches

If you'd like to help test migration patches, you'll need to set up a test environment. Always apply patches to the latest Drupal 8 dev version.

• Learn how to use git to apply patches from the Developer guide on git patching.
• For general patching info, see the Patching section of the Getting Involved Guide.

Help identify root causes of migration issues

If you're experienced with Drupal and its data model, you may be able to help understand the root causes of migration issues. The key is understanding:

• Where the source data comes from in Drupal 6/7
• Where it is supposed to go in Drupal 8

Some tools to help investigate source data:

• Devel module – a great tool for inspecting source data in Drupal 6/7.
• phpMyAdmin or any database browser to examine the source database.
• If you identify a Drupal 6/7 form that stores data but can’t find it in the database, search the Drupal API by copying/pasting a field name and searching for:

site:api.drupal.org <enter your query here>

To examine migration configuration in Drupal 8:

• Visit admin/config/development/configuration/single/export
• Select "migration" as the configuration type
• Select the migration you wish to inspect

A few words about automated migration tests

All bug fixes to Drupal 8 core require automated test coverage. If you're unfamiliar with test automation, fixes can still be contributed without tests. This section is for advanced contributors looking to add tests.

Migrations must be tested to ensure the testbot actually performs the migration. When writing tests for core migrations from D6/D7 to D8, Drupal 8 core uses database fixtures as source data:

• core/modules/migrate_drupal/tests/fixtures/drupal6.php
• core/modules/migrate_drupal/tests/fixtures/drupal7.php
• Learn more about generating database fixtures for migration tests

Actual tests are typically defined in the relevant module’s core test directory, for example: core/modules/comment/tests/src/Kernel/Migrate/d7