Contributing to Migrate

Drupal 8 (or later) core 'Migrate Drupal' module provides API support for Drupal-to-Drupal migrations, and 'Migrate Drupal UI' offers a simple user interface to upgrade from older Drupal versions. 

Report results of your upgrade

When you are upgrading your Drupal 6 or Drupal 7 site to Drupal 8 (or later) make sure to test and verify your results thoroughly. It is possible that you will find something which did not upgrade as you expected. When this happens:  

• First check if the issue is listed at Known issues when upgrading from Drupal 6 or 7 to Drupal 8 (or later)
• If your issue is not listed there, search for open Drupal 6 - Drupal 8 (or later) migration issues or Drupal 7 - Drupal 8 (or later) migration issues.
• If you don’t find an existing issue for the problem you're facing, please create a new issue to core migration system issue queue. Reporting a new migration bug is already a very valuable contribution and helps getting the migrations stable!

When reporting new issues, they go to the 'migration system' component. It is extremely important that you provide as much and as much detailed information that as possible.

• Please provide screenshots of before, from Drupal 6 or Drupal 7, and after,  Drupal 8 (or later) where applicable.
• Describe the problem as specifically as possible.
• Provide additional details on your site that you think might be relevant to this issue.
• Example of a good issue report: https://www.drupal.org/node/2853872
  • The short description, screenshot and the bullet points under the screenshot were created in the original issue report
  • The issue summary was then later updated several times as more and more information was found during the analysis.
  • Keeping the issue summary updated is extremely important part of fixing process. Migrate bugs can sometime be very complex and making sure the issue summaries are up to date will significantly help migrate maintainers and other contributors! 
  • Don’t be shy - your best effort to write as detailed bug report as you can will be appreciated!

Help testing patches

If you want to help testing the migration patches, you’ll need to set up a test environment. Always apply the patches against the latest Drupal 8 (or later) dev version.

• For information on using git to apply patches, please see the git patch contributor guide. 
• For more generic information about patches, please see the Patch section of the Getting Involved Guide. 

Help finding the root causes of the migration issues

If you have a bit more experience with Drupal and its data model, you will most likely be able to help understanding the root causes of the migration bugs. Since we’re talking about data migrations, the most important thing is to understand

• Where the source data is coming from in Drupal 6 or Drupal 7
• And where is it supposed to go in Drupal 8 (or later)

Some tools that will help you to understand where the data is coming from

• Devel module is a great tool for checking the source data in Drupal 6 or Drupal 7
• phpMyAdmin or other database browser will help you to dig where the data is actually coming from in Drupal 6 or Drupal 7
• If you can identify the Drupal 6 or Drupal 7 form where the data is maintained but you can’t find the data from the database, you can always follow the trails by reading the API. Open the Drupal 6 or Drupal 7 form where the data is maintained, copy paste the field and do a google search 

  site:api.drupal.org <enter here what you want to search for>

If you have used the Migrate Upgrade module, the migration configurations can be read in Drupal 8 (or later) as follows

• admin/config/development/configuration/single/export
• Select 'migration' as 'Configuration type'
• Select the migration that you want to inspect

A couple of words about the automated migration tests

All bug fixes that get committed to Drupal 8 (or later) core will need to have test automation coverage. It is perfectly fine to contribute patches without tests if you're not familiar with test automation. This section is intended for advanced contributors who want to contribute with the tests.

The migrations need to be tested so that the testbot actually performs the migrations. When writing tests for core migrations, the database fixtures included in Drupal 8 (or later) core are used as the source data:

• core/modules/migrate_drupal/tests/fixtures/drupal6.php
• core/modules/migrate_drupal/tests/fixtures/drupal7.php
• Read more about the migrate database fixtures 

The actual tests are typically defined in Kernel tests of the module in question, for example tests for the migration of comments are found in in core/modules/comment/tests/src/Kernel/Migrate.