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

1. You will need git, composer, php.  Use the links below to install or use UMD Virtual Workspace which has the necessary tools installed.  
   
   1. Follow the instructions at https://www.atlassian.com/git/tutorials/install-git to get git installed
   2. Install php 7 or 8, https://www.php.net/manual/en/install.php
   3. Install composer https://getcomposer.org/doc/00-intro.md
2. Create a SSH key certificate to checkout your site code from Pantheon
   
   1. From a terminal window, run the command: ssh-keygen
      
      1. This command works on Linux, MacOS, and Windows 10.
   2. Unless you have reason to change it, leave the default location of ~/.ssh/id_rsa as is. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.
   3. A passphrase is recommended to provide greater security, but can conflict with tools that cannot handle them.
   4. Once the files are created, copy the contents of ~/.ssh/id_rsa.pub to your clipboard.
      
      1. Linux and Mac users can cat the file to the terminal and copy the output:
         
         1. cat ~/.ssh/id_rsa.pub
      2. Windows users can achieve the same result with type:
         
         1. type .ssh\id_rsa.pub
      3. ssh-add ~/.ssh/id_rsa
3. Cut and paste the certificate into Pantheon, this is done under your account page

•  

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 "SSH clone URL"
      
      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.
   
   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.
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

• What you need to know about Drupal 7, 8 and 9 on Pantheon
• Drupal Documentation: https://www.drupal.org/docs/upgrading-drupal/how-to-prepare-your-drupal-7-or-8-site-for-drupal-9/upgrading-a-drupal-8-site
• Pantheon Support: How to get Pantheon Support
• Pantheon On-Demand Workshops: https://pantheon.io/workshops
• Pantheon Guides and Documentation
• Pantheon.yml documentation
• Git installation and useage
• Composer installation and usage
• Composer patching
• Pantheon SSH keys
• Windows Subsystem for Linux, if you are having issues with windows missing companents like patching, installing Linux on Windows may be useful