Drupal 9 Upgrade Processes and Considerations

If your site is on Drupal 7 (D7) or an older version, the journey to a Drupal 9 (D9) upgrade is considered the last big migration. With the innovation cycles of Drupal 9 and that of Drupal 8, future major version upgrades will be easy and straightforward.

Our recommended approach is to migrate to Drupal 8 (D8) and continue an easy upgrade to D9 thereafter. Migration to D8 may seem overwhelming as it is not a direct upgrade with the existing codebase. The D8 upgrade is rebuilding a new site and importing your data into it. This is a good opportunity to review and streamline your information architecture and content types.

Considerations

This is a good chance to streamline your content and SEO and remove ineffective areas. A smaller site is faster and easier to maintain and improve.

Drupal contributed modules development are moving quickly. There could be a better option, or existing module is not actively maintained. With ongoing development, comes technical debt. Audits and reviews should be done to avoid and replace unmaintained contrib modules or themes, and to remove unused modules, themes, and libraries.

D8 and above dictate the environment requirements summarized as follows:

• PHP 7.3 and above
• MySQL 5.7, MariaDB 10.3.7, PostgreSQL 10 with the pg_trgm extension, or SQLite 3.26 and above
• Drush 10
• Composer 1.9.1

Process

If your current site is not a composer-based build, it is recommended to convert it to use composer. Composer can be used to manage Drupal and all its third-party dependencies, saving development time in the long run. Continuous updates, dependencies management, semantic versioning, and patch tracking are among the main benefits.

The steps are summarized below:

• Upgrade all contrib modules/themes to latest version on D8.
• Export the latest copy of config.
• Change the installation to a composer-based install. We recommend starting from scratch, copying over custom codes, files, settings.php, and importing the DB.
  
  Note: use drupal/core-recommended
  
  • Convert to a composer install base, https://pantheon.io/docs/guides/composer-convert.
  • If using Pantheon composer build, remove the continuous integration (CI integration). If not using, see https://pantheon.io/docs/guides/drupal-8-composer-no-ci.
  • Can use https://www.drupal.org/project/composerize to generate a working list of modules.
    
• Update .gitignore to correctly track files in git. Refer to https://gist.github.com/ckng/c302099957908fde3f228cb71a771e46.
• Install library using composer via Asset Packagist, see https://www.drupal.org/docs/develop/using-composer/using-composer-to-install-drupal-and-manage-dependencies#third-party-libraries.
  
• Track patches using composer, via cweagans/composer-patches:
  
  "extra": {
"patches": {
"drupal/core": {
"Issue #123455: Add startup configuration for PHP server": "https://www.drupal.org/files/issues/add_a_startup-1543858-30.patch"
}
}
}
  
• Customize Drupal composer scaffold to include/exclude/overwrite changed files. Common examples are .htaccess, robots.txt. See https://www.drupal.org/docs/develop/using-composer/using-drupals-composer-scaffold.

Continue with composer-based install upgrade process.

If you are already using composer for your Drupal install base, you may still pick up some useful ideas from the above optimization.

You should update the Drupal core 8 to the latest version. Both contributed modules and themes should be updated as well. A useful list of tools to help you are:

• Acquia’s Drupal 9 Deprecation Status page
• Upgrade Status Module
• Drupal Check

For your custom modules and themes, you want to check for depreciated APIs and fix the incompatible code. Drupal-rector and Upgrade Rector can help automate the process of fixing depreciated Drupal code.

Update core to Drupal 9 and run update.php. CELEBRATE!

Gotchas

If you are on Pantheon platform, avoid these being committed to Pantheon git repository:

• 'sites/default/files',
• 'wp-content/uploads',
• 'web/sites/default/files',
• 'web/wp-content/uploads'

Webform and libraries are almost always incorrectly installed. Although plugins will be loaded from CDN, the plugins are best local so they can be aggregated to improve performance.

• Recommended way to use composer merge: https://www.drupal.org/node/3003140
• Other ways if the above is not possible: https://www.drupal.org/docs/8/modules/webform/webform-libraries