After a number of Drupal 7 (D7) to Drupal 10 (D10) migrations, we’d like to share our tips and tricks for streamlining the process.
Discovery Process
Our Drupal migration process starts the same way as any other project at ABT, with our comprehensive discovery phase. We do this to make sure that the existing Drupal 7 site is continuing to meet the needs of our customer, and whether there are new features and functionality that can be added during the migration. If the customer would like to refresh the look and feel of the site at the same time, we move on to our design phase. While the design phase is going on, we also march on with the next steps in the migration.
Module Audits
We developed a spreadsheet template (with conditional formatting!) to determine whether the projects used in the Drupal 7 site are Drupal 10-compatible. The Upgrade Status and Upgrade Rector modules help speed this process up, but there is still a little legwork to do to determine version numbers, patches that need to be applied, and to weed out both false positives and false negatives that the modules report.
One thing to watch for is that the upgrade modules will report that a project has a patch to make it Drupal 10-compatible. However, if that patch includes a change to the project’s composer.json file, then the project cannot be patched with the commonly used cweagans/composer-patches library. A developer would have to either remove the project from Composer and check the patched version into the site’s repository, or the developer would have to create a fork of the project and change their composer.json file to pull the project from the forked repository. Both situations are not ideal, as then the developer would have to keep track of project updates and pull in the changes manually.
Luckily, there is a workaround in the mglaman/composer-drupal-lenient project. The composer-drupal-lenient project allows developers to add projects to an allow list that tells Composer to ignore the Drupal core version requirement in a project’s composer.json file. If a project is reported to be Drupal 10 ready, but the maintainer hasn’t created an official Drupal 10-compatible release, then a developer can still pull in the project via Composer.
As far as the module audit spreadsheet itself is concerned, it is a list of all the enabled projects and whether they are custom, require an update, have a D10 version, have moved into core, or have been replaced by another module for D10. This spreadsheet and the outputs of the discovery and design phases feed into the next tool, the specification tool.
Specification Tool
As we worked on Drupal projects, we realized that writing a specification for a Drupal site was just…hard. But, after working with customers hosted with Acquia, we stumbled upon their Drupal Spec Tool and life became much easier. Now, we still write custom feature specifications for custom features, but the basic specification for bundles, fields, menus, Views, and more are handled by the Spec Tool. We copy the existing D7 site’s structure into the tool, and then from there can audit whether to migrate the data, transform it, delete it, or create new structures for new functionality. The tool becomes a living document that describes how the site is configured in a human-readable format, which helps non-technical users. After the site structure is described in the tool, we move on to writing the actual migrations!
Migration Projects
The Drupal 7 to 10 migration process is probably best handled in its own post, but it’s worthwhile to mention the Composer packages and Drupal contributed projects that help us streamline the migration process. Here’s a list of tools that can get you started, and what they do:
- The cweagans/composer-patches and mglaman/composer-drupal-lenient Composer packages mentioned earlier in the article.
- The Upgrade Status and Upgrade Rector projects mentioned earlier in the article.
- Configuration Split: This project is helpful for applying different site configurations for different development environments. In the context of a migration, it can allow you to set different file paths and database connections per environment.
- Media Migration: This project helps move Drupal 7 managed files (and media entities, if the Drupal 7 site used them) into Drupal 10 media entities. It also helps convert the field types and embedded media in content.
- Migrate Plus: The biggest advantage of this project is that migrations can be implemented as configuration entities that can be checked into your source code repository. It also adds migration API extensions and plugins that help with complicated migrations.
- Migrate Tools: This project adds Drush support for Drupal migrations.
- Migrate Conditions: This project adds logic condition process plugins to allow developers to migrate content based on certain conditions. For example, we used the project to migrate a content type to different content types based on a taxonomy term on the content.
- Drush: Drush is a command line tool for Drupal, and provides many other command line functions, besides running migrations, for managing your site on the server.
Check in later for a deep dive of the migration process with tips, tricks, and pitfalls to avoid!
