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. Install git
2. Install php 8
3. Install composer

Create a SSH key certificate to checkout your site code from Pantheon.

From a terminal window, run the command: 

ssh-keygen -b 2048 -t rsa

• This command works on Linux, MacOS, and Windows 10.

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.

A passphrase is recommended to provide greater security, but can conflict with tools that cannot handle them.

Once the files are created, you will need to copy the contents of id_rsa.pub to your clipboard.

• Linux and Mac users can cat the file to the terminal and copy the output:

cat ~/.ssh/id_rsa.pub

• Windows users can achieve the same result with type: type .ssh\id_rsa.pub

type .ssh-add ~/.ssh/id_rsa

• If you put your key file in a different location, change the above to match

Cut and paste the certificate into Pantheon, this is done under your account page at https://dashboard.pantheon.io/personal-settings/profile

 

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"
   
   • 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.

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.

Top

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). If you already have the module installed, make sure you are using version 4 as versions below 4 can cause issues with the upgrade.

1. On your local repo, run the following (if using multidev, make sure you have switched to its branch):

composer require -W --ignore-platform-reqs drupal/upgrade_status:^4

1. • add the changes, commit them and then push them from your local repo to the site repo
   • 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. Find the upgrade status page under Reports" from the toolbar, or by visiting yoursite.umd.edu/admin/reports/upgrade-status and running the report, ex:
   

Uninstall or upgrade modules, 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 11, and updating environmental components.  Custom modules or modules with custom code may have to be individually reviewed.  Uninstalling and upgrading modules, and updating environmental components will be described below.

Top

Uninstall modules

NOTE: 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
   • 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 all site environments (dev, test and live). Uninstalling a module is a content change, which do not promote upward from the development environment like code changes do. 

Alternatively, you can uninstall a module on the live site, and then copy the database back to the test and dev environments.  Copying the database to the lower environments will bring the module uninstall with it, as well as refresh the content.  Copying the database from the live environment can be found on the Pantheon dashboard under Database/Files from the left subnav of each environment.

Top

Updating modules

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.  

• Alternatively you can edit the composer.json file in your site root directory and edit the module version numbers manually.

Next you will need to run the following command to have composer process your change, and make sure the update got the right version:

composer update

• • 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.
• 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.
• 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.
• You may not need to manually update all modules to have a 'clean' 100% from the Upgrade Status module before upgrading to Drupal 11. In the image below, note that each module on the Update section has a Drupal 11 version that matches the installed versions major version (ex Image Optimize has 4.0.1 installed, and 4.1-beta1 is the Drupal 11 compatible version).  When you run the Composer command below to upgrade to Drupal 11, each module is checked to see if there is an update on the same major version branch available, and it is is automatically pulled in if so.

External Data Source

The Drupal module External Data Source is used to pull in information for the news articles on UMD Terp sites.  The contrib module does not have a Drupal 11 release at this time, so the UMD Terp vendor has forked its code, and included a Drupal 11 compatible version as a custom module in the Drupal 11 version of UMD Terp.  The Drupal 11 Composer upgrade process below will remove the contrib module, and pull in the custom version, you should not need to make any changes related to the External Data Source module manually.

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 or update the following lines to these values:

php_version: 8.3
database:
  version: 10.6

1. Commit your pantheon.yml changes to your site repo, and push them to your site. 
2. Check that your site is working with the updated PHP version, and that the Upgrade Status screen reports the updated PHP version.

Promote your Upgrade Status work

Make sure that your module un-installation work has been mirrored to all all environments, and promote your code updates to test and live so that everything is in sync.

Top

Drupal core and UMD Terp Drupal 11 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:^11' 'drupal/core-composer-scaffold:^11' 'drupal/core-project-message:^11' 'pantheon-systems/drupal-integrations:^11' 'umd_digital/umd_terp:^11' 'umd_digital/umd_terp_base:^11' -W --no-update

This will set your composer.json to Drupal 11, 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:^11' 'umd_digital/umd_terp_base:^11'

If you have a "require-dev" section of your composer.json, you can either change that to 11, or delete it.

Notes:

• Make sure that the ^ marks stay in the command.  If you see upgrades to only Drupal 11.0.0 or UMD Terp Base 11.0.0, check that each line 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

composer update

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 11.

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. You may need to run database updates on your site.

Once all issues are remediated, promote the code to Test and Live. 

Top

UMD Terp and the UMD Design System

This update brings most of the UMD Terp elements to the UMD Design System standard, designsystem.umd.edu.  Some notes from that transition are as follows:

• The UMD Design System does not have a 'Dark Mode' for all options that had it previous.  Of note is that if you were using the Dark Mode header in theme settings, some logos may need to be changed over from white to dark.
• If you use a list in a card group there will be formatting issues as the UMD Design system did not support that combination
• The Schoolwide Header was reworked, you may need to re-select what options you display at sitename.umd.edu/admin/config/umd_schoolwide_header/config
• The footer uses the UMD Design System simple footer, with no user defined menus.  The existing menu data has been preserved, and we hope to incorporate the existing footer menus into a reworked footer based on the UMD Design System mega menu in a future update.

Additional Resources

• Pantheon Support: How to get Pantheon Support
• Pantheon On-Demand Workshops
• Pantheon Guides and Documentation
• Pantheon.yml documentation
• Pantheon Terminus
• Git installation and useage
• Composer installation and usage
• 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

Top