Notes, tips, and tricks for upgrading a Drupal 8 site to Drupal 9

Moving to Drupal 9 from Drupal 8 does not involve near as much planning and preparation work as previous major version upgrades thanks to changes the Drupal organization has made to the development process.  Instead of Drupal 9 introducing a new batch of features, new features have been added gradually over the major point releases of Drupal 8.  The key changes with the first release of Drupal 9 will be to remove deprecated (old and no longer used) code, and to upgrade the underlying Symfony framework.  On the surface, though, you should not see any notable differences between Drupal 8.9 and Drupal 9.0, assuming you have prepared your site properly.

Preparation

Basic Requirements

• Drupal 9 requires PHP 7.3 or higher (7.4 is preferred). If you are on OIT Web Hosting, you should be able to set your PHP version now via your site's Plesk Control Panel.

• Drupal 9 requires a settings.php change:
  • The line beginning with "$config_directories['sync'] =" has to be changed to "$settings['config_sync_directory'] ="

  • Note: You can do this before upgrading, as Drupal 8.9 will work with either version of the setting.

• To upgrade to Drupal 9, you must be on Drupal 8.9.0 or higher.
  • If you are already on 8.9, make sure you have the latest patch release to get the smoothest transition

  • If you are on anything earlier, upgrade to the latest patch release of 8.9 first, then upgrade to the latest 9.0 release.

• Drupal 9 requires all active themes and modules to declare Drupal 9 compatibility:
  • Compatibility is indicated by a line in the theme or module's .info.yml file that starts with "core_version_requirement:"
  • Check and update all custom and contrib modules.
• Drupal 9 (as did Drupal 8.9) uses CKEditor 4.14.0, but Drupal 9 seems to be stricter about CKEditor plugins. If you are using any add-on CKEditor plugins, check each one to see if there's a 4.14 specific version and upgrade as needed. Composer should maintain the compatible plugin version with a Drupal 9-compatible release.
  
  As an example, Balloon Panel, used by Accessibility Checker, was one that needs to be up-to-date to work in Drupal 9.

Checking Module / Theme Compatibility

There are several tools available that are supposed to check your site's modules and themes for Drupal 9 compatibility. The present options either require the ability to run PHP at the command line or require your site to be managed through Composer (such as Drupal Express websites).

Upgrade Status Module

The Upgrade Status module can perform a website audit to determine which modules, themes, and add-ons are Drupal 9 compatible.

Command Line

If you are comfortable with running simple commands at the Linux command line, you can get a quick overview of your modules declared compatibility by going to the main modules directory and running the following command:

  grep "core" */*info*

For any module where you do not see a line with "^9" near the end, you'll need to do some testing and research to see if the module will work with Drupal 9.  Check first for a new major version release, and if there is none, you could try the instructions given below for testing a previously Untested Release to see if it causes any problems.

Process

Once you've completed all of the preparatory steps, upgrading is the same as if you were upgrading to another point release of Drupal 8. 

As with any major update, make a full backup (filesystem and database) before you begin, just to be safe.

Afterward, test major website capabilities thoroughly, since a lot of old code has been removed and the underlying Symfony engine has received a major upgrade.

Institute Communications update process

Refer to Institute Communications' gt_installer Drupal 8 to Drupal 9 update process to update GT Theme, GT Tools, and GT Profile to their latest versions.

Issues

Semantic Numbering - New Major Releases

As more time goes by, more module developers will move to the new semantic numbering system that is not tied to a Drupal version number (e.g. 7.x-1.0). Typically, if a module was at say version "8.x-3.5" then the next major release done under the new numbering system would be "4.0.0". You'll have to check carefully for this change, as Drupal alerts major version releases (8.x-3.5 to 4.0, for example) as "Other versions available".

However, in the case of modules like Webform, you may find you are expected to upgrade to the next major version when you upgrade your site to Drupal 9. Module version updates to the next major version can be done easily if you manage your site with Composer. Otherwise, you'll have to do this by hand at the filesystem level (Drupal won't upgrade to a new major version via the GUI).

As with most major version upgrades, manually run schema updates (go to update.php after updating).

Known Problem Modules

• Devel has a new 4.0.0 release just for Drupal 9, but the popular Kint debugger sub-module is gone from 4.0.x. To get that functionality you have to use composer to install a Kint plugin for Devel 4.0.x or use the devel_kint_extras module. That's a big complication if your site is not set up to be managed by composer. As a workaround, you can download the PHAR version of Kint and manually include it in your site to get its functionality. Please note that the manual library process is not as streamlined an install as a prepackaged module.

• Webform 8.x-5 is not compatible with Drupal 9 at all and will actually break the update.php process. If you use Webform, do not attempt to upgrade to Drupal 9 until you have upgraded Webform to its new 6.0 release.