Special release note: Updating to Drupal 9

Important

Sites created prior to March 9, 2021 were based on Drupal core version 8. When these sites update to a subsequent version (starting with 3.0.0-beta.10), they will reference Drupal 9. Because this constitutes a major version increment, site maintainers will need to perform codebase checks and scaffolding changes as part of this update.

Developers should be ready to budget time for this more involved update, and should test in a sandbox environment before deploying these updates to a production site.

Tasks should be performed in the order listed below.

Sites created subsequent to March 9, 2021 do not need to take these actions.

Contents

Tasks not specific to the UT Drupal Kit

The following are compatibility requirements for any Drupal 9 site, not just the UT Drupal Kit. As such, the documentation provided below is only meant to be a starting point for performing these tasks.

For an overview of the Drupal 9 update process and recommendations, read https://www.drupal.org/docs/upgrading-drupal/how-to-prepare-your-drupal-7-or-8-site-for-drupal-9/upgrading-a-drupal-8-site.

Audit and update contributed modules to Drupal 9 compatible versions

Any contributed modules you added explicitly to your codebase must be Drupal 9 compatible. Contributed modules added via UT Drupal Kit are Drupal 9 compatible as of the March 9 update, so you don’t need to audit those contributed modules separately.

You can check if a contributed module has a Drupal 9 compatible release by going to its project page on drupal.org. The “Downloads” section of available releases will specify whether the latest version is Drupal 9 compatible.

Audit and remediate Drupal deprecations in custom code

Drupal 9 replaced many core functions found in Drupal 8. If you have written custom code for your site, you will need to make sure that it doesn’t reference deprecated functions. See https://www.drupal.org/docs/updating-drupal/how-to-prepare-your-drupal-7-or-8-site-for-drupal-9/deprecation-checking-and

Audit and remediate PHP version deprecations

Drupal 9 requires PHP 7.3. Code that uses deprecated PHP methods could exist in custom code or in contributed modules that you added that are out of date. Ensuring PHP 7.3 compatibility should consist of automated auditing techniques, such as what is described in https://www.drupal.org/node/2924272 , as well as manual functional testing of custom code or contributed functionality. If you updated any contributed modules to Drupal 9 compatible version (checkbox 1, above), that module is also guaranteed to be PHP 7.3 compatible.

Set infrastructure to use PHP 7.3

If hosting your site on Pantheon, the version of PHP that Pantheon uses for your site is defined in the pantheon.yml file in your codebase. If you installed a Drupal Kit site prior to March 9, 2021, this file will contain the PHP value 7.2. Change it to 7.3. See more at https://pantheon.io/docs/php-versions#configure-php-version If hosting on UT Web, the site PHP version can be set to 7.3 in Virtualmin. See https://wikis.utexas.edu/display/utweb/PHP+7.3

Upgrade to Drush 10 (if applicable)

If you use Drush for development, you will need to upgrade to version 10. See the following references:

Tasks specific to the UT Drupal Kit

Perform these tasks after to the generic tasks listed above. Doing so will ensure that dependency versions in the codebase are more up-to-date, which will streamline the Drupal core update via Composer.

Update root-level Composer packages for Drupal 9 / PHP 7.3 compatibility

  1. If you have not yet done so, follow the procedure described in Package incompatibility with Composer 2 to ensure that root-level Composer packages are Drupal 9 and PHP 7.3 compatible.

  2. In your composer.json file, change "drupal/core-composer-scaffold": "^8", to "drupal/core-composer-scaffold": "^9",.

Update Drupal Kit add-ons for Drupal 9 compatibility

If you added ITS-provided add-ons, they will need to be updated. Run composer outdated utexas/* to see which packages have available updates. Then update applicable packages using standard Composer methodology (if you use a floating version constraint, for example, update with composer update utexas/<name of package> --with-all-dependencies).

To be Drupal 9 compatible, the version must be at least as high as shown below (not all packages may be present in your site):

utexas/utnews:1.0.0-alpha.6
utexas/utprof:1.0.0-alpha.7
utexas/utevent:1.0.0-alpha.4
utexas/utexas_pantheon_saml_auth:1.0.0-alpha.6
utexas/utexas_saml_auth_helper:1.0.0-alpha.3

Update Drupal Kit kernel (and Drupal core)

The package utexas/utdk_profile includes the dependency to Drupal core. Updating this package will consequently update the site codebase from Drupal 8 to Drupal 9.

The update process should be straightforward but may differ depending on the site: if the site includes other dependencies, for example, or hasn’t updated some dependencies recently, additional parameters may need to be included so that Composer can properly resolve the dependency tree.

For a simple site, this final code update step will be achievable by running composer update utexas/utdk_profile --with-all-dependencies.

If the command refuses to perform the update, with message about being unable to resolve dependency conflicts, the developer may need to add additional dependencies to the command so that they can be simultaneously resolved. For example, if the message includes dependency conflicts for symfony or drush, the following command should provide proper resolution.

composer update utexas/utdk_profile symfony/* drush/* --with-all-dependencies

You can confirm that the update to Drupal 9 has been successful by running composer show utexas/utdk_profile and verifying that the output shows the version of drupal/core-recommended to be Drupal 9.

Note

As with all updates of a Drupal site, database updates need to be run after the codebase change has been made.