Tools

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

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
5. Cut and paste the certificate into Pantheon, this is done under your account page

Upgrade Process

Upgrade Prep

Create a Multidev environment to test the update (Optional, but recommended) 

Multidevs 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

1. Click on the 'Connection Info' on the top right of the site dashboard.
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.

Install and enable the Upgrade Status module version 4.

This module will show site readiness for a Drupal upgrade, example screenshot from the module page, https://www.drupal.org/files/project-images/UpgradeStatus3FullUI.png  If you already have the module installed, make sure you are using version 4 as versions below 4 can cause issues with the Drupal 10 upgrade.

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:^4
   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
3. Run the upgrade status report by visiting /admin/reports/upgrade-status and running the report, ex:
   

Uninstall, upgrade or fix issues identified by the upgrade status module report.  Most likely this will involve uninstalling incompatible/deprecated modules, updating modules to newer versions that are compatible with Drupal 10, and updating environmental components, described more below.  Custom modules or modules with custom code may have to be individually reviewed.

Uninstall modules

!Important! uninstall modules from the Drupal website interface first before removing the code.  If the module code is removed first, the Drupal site will still have a record of the module, but will not be able to find its code, and will throw errors.

1. Find the 'Uninstall module' tab under 'Extend" from your sites admin toolbar
   
2. uninstall old, unneeded, or deprecated modules from the list, this will remove all that modules content/settings
3. For deprecated themes, look under the 'Appearance' tab
   1. Note: if you encounter issues getting the 'Stable' theme uninstalled, DIT can run a quick Terminus command to help
4. Once a module has been uninstalled, the code for the module can be removed from your site repo
   • Modules can be removed with the command "composer remove drupal/module_name"
   • add and commit your changes, then push them to the site.
   • review the Upgrade Status page to confirm that the modules have been removed, you may need to clear the site caches to see the change reflected.

Another important step; any module uninstall actions done via the Drupal site UI must be repeated on the live site as well as the development environment. Uninstalling a module is a content change, which do not promote upward from the development environment like code changes do.

Updating modules

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, replacing x with the new version.
2. Next run the command "composer update" to have composer process your change, and make sure the update got the right version.
   1. If after running "composer update" the version is not changing or is not correct, you may need to edit your composer.json and change the version number by hand.
3. Once the module version has been updated via composer on your local repo and a successful "composer update" run has been processed; add, commit and push them with git.
4. 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 or from within the Drupal site.

Update Pantheon system environmental values

The quick version is below, for a more detailed explanation we have this KB article

1. within the pantheon.yml file in the root of your site repo, add the following lines
   
   1. php_version: 8.1
2. Commit your pantheon.yml changes to your site repo, and push them to your site. 
3. Check that your site is working with the updated PHP version, and that the Upgrade Status screen reports the updated PHP version.

Upgrade to CKEditor 5

Make sure you are using version 5 of CKEditor, for more information we have the following KB article

Promote your Upgrade Status work

Uninstall all the modules on Live that you uninstalled on dev, and promote your Drupal 9 code updates to test and live so that everything is in sync.

Composer.json Work

Edit composer.json

!Important! from composer.json, copy the entire "require": { } somewhere safe

Pull in new Pantheon upstream settings

Run the following from within your site repo to update to the newer Pantheon upstream:
git pull -Xtheirs https://github.com/pantheon-upstreams/drupal-composer-managed.git main --ff

This will overwrite the existing composer.json with Pantheons updated version, this will transition your site to using the newest Pantheon upstream bringing with it new updating capabilities, but will require you to restore your module list.

Edit composer.json

In the "require" section keep:
        "pantheon-upstreams/upstream-configuration": "dev-main",
        "composer/installers": "^1.9",
        "drupal/core-composer-scaffold": "^9.2",
        "drupal/core-recommended": "^9.2",
        "pantheon-systems/drupal-integrations": "^9",
        "cweagans/composer-patches": "^1.7",
        "drush/drush": "^11 || ^12",

1. re-add your site modules to 'require' section from the safe-keeping copy, do not re-add ones that are are part of the list above
2. add pantheons advanced page cache if it is not there to the require section.
   1. require as:
      "drupal/pantheon_advanced_page_cache": "^2",
3. if using Upgrade status, make sure it is set to v4 

Change the following below the 'require' section

"minimum-stability": "stable",
to
"minimum-stability": "dev",

Delete the following lines:

"require-dev": {
        "drupal/core-dev": "^9.2"
    },

Run the 'composer update' command

Fix any issues identified by composer update run.  If there issues found with module versioning, check the module project page to see if there are newer or updated versions that may have fixes.  Note that the last entry in the 'require' section does not have a comma after it.

Drupal core and UMD Terp Drupal 10 update

From your repo (or the multidev branch on your local repo if you are using a multidev), run the following:

composer require 'drupal/core-recommended:^10' 'drupal/core-composer-scaffold:^10' 'drupal/core-project-message:^10' 'pantheon-systems/drupal-integrations:^10' 'umd_digital/umd_terp:^10' 'umd_digital/umd_terp_base:^10' -W --no-update

This will set your composer.json to Drupal 10, as well as the versions of Pantheon and UMD Terp.  If you are not using the UMD Terp theme, you can remove the segment 'umd_digital/umd_terp:^10' 'umd_digital/umd_terp_base:^10'

Notes:

• Make sure that the ^ marks stay in the command.  If you see upgrades to only Drupal 10.0.0 or UMD Terp Base 10.0.0, check that each line above in your composer.json still has a ^ as this is what allows it to get each new minor version.
• if you are using windows, it may complain about the ' marks in the command, if so just remove all them all. 

Run the 'composer update' command

Fix any issues identified by composer update run.  If there are issues found with module versioning, check the module project page to see if there are newer or updated versions that may have fixes.  You may need to update to module versions that list they are compatible with Drupal 10.

Commit and push

Once you get a clean "composer update" run, add your changes, commit changes, and push to server

Review the site.

Review the site status page, check for errors and updates that may need to be done. Once all issues are remediated, promote the code to Test and Live. 

After Upgrade

once the upgrade is tested and push to test and live, utilize Pantheons command line tool Terminus, or ask DIT to run:
terminus site:upstream:set $SITE drupal-composer-managed

1. replace $SITE with your sites machine name
   1. if unsure of your sites machine name, you can run
      terminus site:list to display them
2. this will set your sites dashboard to use the current upstream for your site that was added in as part of the upgrade process

Additional Resources

• Pantheon Support: How to get Pantheon Support
• Pantheon On-Demand Workshops: https://pantheon.io/workshops
• Pantheon Guides and Documentation
• Pantheon.yml documentation
• Pantheon Terminus
• 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