Home Approach Services Mission Team Careers Blog Contact

Easy commit credits with migrations, part 1: Migrating Drupal Core

8 minute read Published: Author: Matt Parker
Drupal Planet , Migrations , Drupal

Easy commit credits with migrations, part 1: Migrating Drupal Core

This is the first in a series of blog posts on writing migrations for contrib modules:

Stay tuned for more in this series!

Background

Besides helping small teams do big things at Consensus Enterprises during the week, I also work part-time for a small family business. Naturally, I built the business’ website in Drupal (initially Drupal 6, now Drupal 7), and, like many other small sites, I took a low-code approach by assembling its functionality using configuration and 63 contrib projects. To make the best use of my budget, I focused my custom development efforts on making a unique theme.

But, 8 years on, the website’s theme is looking a bit dated, Drupal 7 is quickly reaching the end of free support, and the small family business I built it for doesn’t have a budget for paid Drupal 7 support. I want to upgrade the site to Drupal 9.

Happily, Drupal 8 and 9 have a simple Drupal-to-Drupal migration wizard, and the community has a fantastic Core migration team, so migrating from D7 Core to D8+ Core is easy and has a great user experience! (seriously — the past and present Core migration team deserves a lot of credit!)

Problem / motivation

While migrating Drupal 6 or 7 Core to Drupal 8 or 9 Core is extremely easy, there are still many contrib modules without any migrations. Any sites built using a low-code approach likely use a lot of contrib modules — and are therefore blocked from migrating because of contrib!

For my small business website, when I went through the migration wizard, and reached the “What will be upgraded?” step, I saw 104 “Modules that will not be upgraded”, compared with only 32 “Modules that will be upgraded”1!

Honestly, I felt pretty discouraged when I saw that, even though I have the knowledge and experience to write the migrations myself!

I don’t think it would be too much of a stretch to imagine that other Site Builders faced with the same situation might consider putting off the upgrade, or abandoning Drupal for a closed hosting platform.

As of this writing, the official Usage statistics for Drupal Core show that there are around 600,000 other Drupal 7 sites — Drupal 7 still powers about 60% of all Drupal sites! (This fact should, perhaps, garner more attention than it does.)

Anyway, During the April 2021 DrupalCon, when Dries said that we need to go back to our Site Builder roots and make Drupal the go-to technology for site builders experience, he hit the nail on the head… Migrating contrib is part of the Site Builder experience too!

How can I help? Why should I help?

Hopefully, your thought is, “I work with Drupal too, and I want to help the Drupal community achieve its strategic initiatives — Can I help?” The answer is, “Yes!”

It is actually pretty easy to write migrations! This makes them a great way for you and/or your employer to gain recognition in the Drupal community through contribution credits. Plus, you’ll get some valuable experience with both Drupal 7 and 8.

Proposed resolution

In this blog series, I will walk you through the ways that I contribute to improve the migration experience for Site Builders, so that you can do those things too! Hopefully, by combining our efforts, you and I can make things easier for anyone who needs to migrate a Drupal 7 site to Drupal 8 or 9 (myself included), and help the Drupal community to achieve our strategic initiatives!

This blog series will be geared towards people who:

  1. know how to download and install Drupal 8 or 9 and contrib modules on their workstation (with or without composer),
  2. know how to apply a patch,
  3. are comfortable doing a little bit of development work (mainly writing YAML files),
  4. are self-motivated to read publicly-available documentation and code,
  5. want to help, and,
  6. don’t mind engaging with the Drupal community.

Steps to complete

Let’s start off this blog series with something easy: setting up test sites and running a simple migration of Drupal core.

Setting up your test sites

First, you need to set up a Drupal 7 site to be your migration source. If you haven’t set up Drupal 7 before, it’s pretty easy: download the tarball or zip from the Core project page, extract it into a folder, set your HTTP Server (ideally Apache) to serve the folder containing index.php (there is no web/ or html/ folder in D7), and visit the site in a web browser to begin the installation process (which looks a lot like the Drupal 8 or 9 install process). Install the D7 site using the Standard install profile in the first step.

You’ll also need to set up a Drupal 9 test site to be your migration destination. This blog series assumes you already know how to do this. Install the D9 site using the Standard install profile in the first step.

A note about Drupal 6

Drupal 6 has much less usage than Drupal 7 (about 17,000 sites, or about 1.7% of Drupal’s total market share, as of this writing), and it requires a version of PHP between 4.3.5 and 5.3.

You can certainly test migrations with Drupal 6 if you want, but be aware that it has already reached end-of-life and has known security vulnerabilities (so only install it where it can be accessed by people you trust, i.e.: not visible to the Internet), and while its install process is similar to D7’s, its PHP version requirements are not, and switching PHP versions will make it annoying to work with.

Preparing data and config to migrate

Once you’ve got the Drupal 7 site set up, enable some modules (core modules for now - we’ll talk about contrib modules in a future post), configure them, and create a small amount of content. Keep track of what you’re doing, so you can see how it gets migrated later.

Running the migration

Here’s where it gets interesting! On your Drupal 9 site,

  1. At /admin/modules, install core’s Migrate (migrate), Migrate Drupal (migrate_drupal), and Migrate Drupal UI (migrate_drupal_ui) modules (in the “Migration” group).
    Make sure any other modules that you installed/enabled on the Drupal 7 site (i.e.: when you were creating data to migrate) are also installed/enabled on the D9 site.
  2. If you wish, make a database backup of the D9 site, so that you can easily re-run the migration process (at time-of-writing, rollbacks were not yet supported through the user interface - although you could run them from the command-line).
  3. Start the migration wizard by going to /upgrade:
    1. Read the first page and click Continue
    2. On the second page, select Drupal 7 as the version of Drupal you’re migrating from, choose the database type (note MariaDB is roughly equivalent to MySQL), and enter the D7 site’s database connection information (i.e.: so the D9 site can connect to the D7 site’s database directly). Set up the Source files section if applicable, and click Review upgrade.
      • If you’re using [Ddev][ddev], make sure both the D7 and D9 projects are running; then the “Database host” should be ddev-D7_PROJECT_NAME-db, and the “Port number” should be 3306
      • If you’re using Lando, make sure both the D7 and D9 apps are running; then the “Database host” should be database.D7_APP_NAME.internal, and the “Port number” should be 3306
    3. If you see an “Upgrade analysis report”, read it and click I acknowledge... (multilingual migrations can be flakey)
    4. Read the “What will be upgraded?” report, and click Perform upgrade
      • If you enabled some modules on D7, but you didn’t enable the corresponding modules in D9 before starting the upgrade process, they will appear as “Modules that will not be upgraded” here.
      • Contrib modules without migrations — what this blog series is intended to help change — will appear as “Modules that will not be upgraded” in this step of the migration wizard.
    5. When the upgrade is complete, you’ll be returned to the site’s front page.

Congratulations, you’re done: you can now explore the D9 site and see the users, content, configuration, etc. that was migrated from the D7 site!

If you go back to /upgrade, you’ll see “An upgrade has already been performed on this site”, and a button to “Import new configuration and content from the old site”, i.e.: things that had changed on the D7 site since the last migration.

Next steps

If you’d like to test out some already-working contrib migrations, try out the Recipe module.

In the next blog post, we’ll talk about reviewing migration patches.

One last thing: a Proposal for a migration issue tag

To close off this blog post, I’d like to propose that the Drupal.org issue tag maintainers add an official migration issue tag to the list of official issue tags.

A migration tag would make it a lot easier for Site Builders to find patches for their modules; and for contributors to write and review those patches.

You can weigh in on this proposal in issue #3227012

  1. I thought you said “63 contrib projects” earlier! Where did 103 modules come from? Recall that a project can have sub-modules/sub-themes - turns out 25 were sub-modules. 17 more were Features (i.e.: what we used before the Configuration Management Initiative). Another 5 were custom modules - I’ve gotta write migrations for those ones myself. ↩︎

The article Easy commit credits with migrations, part 1: Migrating Drupal Core first appeared on the Consensus Enterprises blog.

We've disabled blog comments to prevent spam, but if you have questions or comments about this post, get in touch!