Upgrade From Drupal 8 to Drupal 9


Background

Vendor support for Drupal 8 ends in November, 2021.  Site owners are responsible for upgrading their sites from Drupal 8 to Drupal 9 no later than January 31, 2022.  If your site has been migrated to the Pantheon platform, please use the below instructions to complete the upgrade.

Tools

You will need git, composer, php

Upgrade Process

  1. (Optional, but recommended) Create a Multidev environment to test the update
    1. Multidev are development environments for teams that allows a developer to fork the entire stack (code and content), work independently, then merge the code changes back into the master. Each forked branch will have its own separate development environment, including database and files.Check out the site project repository to your local machine
  2. Check out the site project repository to your local machine
    1. Click on the 'Connection Info' on the top right.
    2. Copy the line under "
      1. If when attempting to check out the repo you receive the message "Connections Fail With: no matching host key type found. Their offer: ssh-rsa", please see the Pantheon SSH Key doc in the resources section below for troubleshooting steps.
    3. Git by default checks out the main 'origin/master' branch, which is attached to the dev version of your site, if you are using the multidev development method, run the following commands to check out your multidev branch:  'git pull' then 'git checkout --track origin/my-multidev-branch-name' without the ' marks.
  3. Install and enable the Upgrade Status module. This module will show site readiness for Drupal 9, from the example screenshot from the module page, https://www.drupal.org/files/project-images/UpgradeStatus3FullUI.png
    1. On your local repo, run the following (if using multidev, make sure you have switched to its branch):
      1. composer require -W --ignore-platform-reqs drupal/upgrade_status
      2. add the changes, commit them and then push them from your local repo to the site repo
      3. The upgrade status module will now be added to your Pantheon site
    2. Enable the module from the Extend menu on your Drupal site
  4. Run the upgrade status report by visiting /admin/reports/upgrade-status and running the report.
  5. Update, remove or fix issues identified by the upgrade status, most likely this will involve updating modules to newer versions that are compatible with Drupal 9
    1. Modules can be updated from your local repo with Composer with the command "composer require drupal/module_name" or "composer require drupal/module_name:^x" if you need a certain version.
    2. Once the module version has been updated via composer on your local repo; add, commit and push them with git.
    3. It may be necessary to clear the caches after making fixes for them to show on the upgrade status page, this can be done from your Pantheon dashboard in the top right.
  6. !IMPORTANT! - if you have the UMD Terp theme on your site, it will be necessary to run the database update script after updating UMD Terp and UMD Terp Base to their current versions, and, until the external_data_source module is updated, patch the module used as it is used by UMD Terp but has a bug.
    1. updating the UMD Terp and UMD Terp Base can be done with the following in your local repo:
      composer require umd_digital/umd_terp
      composer require umd_digital/umd_terp_base
    2. Once you have updated to the most recent UMD Terp versions in your local repo, add the changes, commit the changes and push then as normal
    3. With the current versions confirmed on your site, visit yoursite-umd.pantheonsite.io/update.php
    4. Running these updates is needed to prevent issues for your site during and after the Drupal upgrade.
    5. Once you have updated to Drupal 9 below, you will need to patch the External Data Source Module that UMD Terp uses, within your repo;
      1. Run this composer command: composer req cweagans/composer-patches
      2. In the repo, edit your composer.json file and then add this to the bottom of the 'extras' section:
        "patches": {
                    "drupal/external_data_source": {
                    "Replace EntityManagerInterface with EntityTypeManagerInterface": "https://www.drupal.org/files/issues/2021-01-25/replace-entityManagerInaterface-3194516-1.patch"
                    }
                }
         
        NOTE: the last bracketed section in each composer.json block has no comma after.  If there was no "patches" section before, you will need to add a comma above as you are adding a new last section, so the full text may be:
                },
                "patches": {
                    "drupal/external_data_source": {
                    "Replace EntityManagerInterface with EntityTypeManagerInterface": "https://www.drupal.org/files/issues/2021-01-25/replace-entityManagerInaterface-3194516-1.patch"
                    }
                }
      3. run this composer command: composer update
      4. with git, add, commit and push these changes.
      5. visit yoursite-umd.pantheonsite.io/update.php again to run another database update to confirm all the changes.
  7. Update database driver version
    1. within the pantheon.yml file in the root of the repo, add the following lines
      1. database:
          version: 10.4
  8. Update Drupal Core
    1. From the multidev branch on your local repo, run the following:
      1. composer require -W --ignore-platform-reqs drupal/core-recommended:^9 pantheon-systems/drupal-integrations:^9 drush/drush:^10
        1. If you encounter issues with core-recommended errors, try the following troubleshooting lines instead:
          1. Look for drupal/core-recommended or drupal/core in composer.json and remove the line(s):
            "drupal/core-recommended": "^8.9.0"
            Then run composer update again:
            composer update

            in composer.json Change to "drupal/core-recommended": "^9",
            in composer.json Change "drush/drush": "^10"
            Run
            composer update

            Run
            composer require -W --ignore-platform-reqs pantheon-systems/drupal-integrations:^9

          2. Alternatively try:
            composer require drupal/core-recommended:^9 drupal/core-composer-scaffold:^9 drupal/core-project-message:^9 pantheon-systems/drupal-integrations:^9 drush/drush:^10 --update-with-dependencies --no-update
    2. Fix any remaining issues that were missed by the Upgrade Status module that prevent upgrading.
    3. Once the issues are remediated, add and commit the updates and push the changes to the site repo
  9. Review the site.
  10. Once all issues are remediated, promote the code to Test and Live

Additional Resources