Updating and upgrading Drupal

by Gisle Hannemyr

This page is a placeholder.

Introduction
Final word

Drupal extensions mentioned in this chapter: Backup and Migrate.

Introduction

Semantic versioning

Semantic versioning is a specification for numbering software releases. It is being used by more and more free software projects, including Drupal. Semantic versioning is only meaningful if the package has a public API.

Semantic version uses three integers for the release version. These are:

Major version. Upgrades will break the API.
Minor version. For introducing new features. Backwards compatible with API.
Patch. For bug and security fixes. Backwards compatible with API.

Prerequisites

These instructions assume that you are familiar with the CLI, and have the following programs installed on your server:

Git
Composer
Drush

If you subscribe to the managed Drupal hosting service that is provided Hannemyr Nye Medier AS, your webhost is already set up for with you with these programs, as well as a fully composerized clean install of the most recent stable version of Drupal. If your website is hosted elsewere, you may need to install these programs yourself, or get your hosting provider to install them for you.

Before updating or upgrading yout website, you must also make sure that these prerequisites are satisfied:

That the site is fully and correctly composerized. I.e. that all extensions has been installed with Composer, you can do this that making sure that all installed extensions has a matching entry in the require section in your site's composer.json, with a version number matching the version that is actually installed.

drupal/recommended-project

Make sure your site already is maintained with Composer and fully composerized using the template drupal/core-recommended.

Doing a minor update

Minor updates are issued frequently for the Drupal core. It may happen twice a month, on the first Wednesday (bug fixes) and third Wednesday( security fixes).

technical A “minor update” in Drupal-speak is any update that will not break the API. Updating the core version 9.5.10 to 9.5.11 is a minor update, as is updating from version 9.4.0 to 9.5.11. Updating from version 9.5.11 to 10.1.6 is a major update.

A minor update may add requested features, fix bugs and/or deal with security issues. Usually, you want to install a minor update as soon as possible after it is released to maintain the integrity and security for your Drupal installation.

Doing minor updates of the Drupal core is usually quick and painless, provided you've observed Drupal's prime directive, which is: Do not hack the core. Likewise, you should not hack extensions that are maintained elsewhere. This essentially means that you should avoid touching any code outside the directories modules/custom and themes.

If your installation is clean (i.e. you haven't hacked core), and your file system permissions are set correctly, you can do bring the core up to the latest version by using the CLI. The preferred method for updating Drupal 8 is using Composer.

In order to do a minor update of the Drupal core and extensions, you need to go through the following seven steps:

In the Administrative GUI, navigate to Manage » Reports » Status report. Check status and fix all errors and warnings before proceeding.
Before attempting any update, make sure to back up the database using the Backup and Migrate extension. That way you can roll back if anything goes wrong with the update.
In the CLI, navigate to the siteroot (i.e. the directory where the website's vendor direcory is.
First update the Drupal core. Run this command:

$ composer update 'drupal/core-*' --with-dependencies

Then update all extensions. Run this command:

$ composer update 'drupal/*' --with-dependencies

To complate the update, use Drush to run required database updates and rebuild caches. To do this, use this pair of commands:

$ drush updb
$ drush cr

Finally, in the Administrative GUI, navigate to Manage » Reports » Status report agian. Check status and fix all errors and warnings.

tip If you are not able to update, you may want to read about troubleshooting composer problems.

Upgrading a website from Drupal 9 to Drupal 10

that it also is updated to the latest minor version of the Drupal 9 branch (currently 9.5.11). Also make sure all extensions are updated to their latest stable version, and that the version that is installed is compatible with Drupal 10. Those that are not compatible with need to be dealt with on a individual basis (e.g. patched, using dev-versions, uninstalled, etc.).

Before you start you should make an inventory of all contributed extensions and their configuration. You may need to remove them in order to able to update using Composer. With an inventory, you can reinstall after updating.

To check if your site is ready, use the Upgrade Status module.

tip The project page suggests that you need to install Drupal's developer dependencies. In my experience, it works better without. You don't need to install these.

If installed on a Drupal 8 site, it will check readyness for Drupal 9. If installed on a Drupal 9 site, it will check readyness for Drupal 10. You must install it using Composer, and then enable it:

$ composer require  'drupal/upgrade_status:^4.0'
$ drush en upgrade_status

To use it from the CLI, it requires Drush ver. 11. If the site is not running that version, you can make it a requirement with this Composer command:

$ composer require 'drush/drush:^11.0'

However, I recommend using it from the GUI. To do so, navigate to Reports » Update status and select the project to scan. It will produce a status report. If a website is ready to be upgraded, it will show "100 %" in the circle on the right edge of the page:

When a site is ready to be upgraded, it is indicated by 100 %.

If the reports complains about "Deprecated or obsolete core extensions installed", uninstall these before upgrading. To uninstall hidden deprecated themes, edit the theme's .info.yml and set the "hidden" key false.

Before proceeding with the upgrade uninstall and remove Upgrade Status:

$ drush pmu upgrade_status
$ composer remove  drupal/upgrade_status

Provided the Drupal 9 are maintained using Composer you shall be able to upgrade to Drupal 10 with the following steps:

First change directory to the siteroot (the directory where composer.json lives).

Temporarily add write access to protected files and directories:

$ chmod 777 web/sites/default
$ chmod 666 web/sites/default/*settings.php
$ chmod 666 web/sites/default/*services.yml

Next, require the Drupal 10 version of these three packackages with dependencies. We use --no-update to avoid a chicken-and-egg problem with mutual dependencies.

$ composer require 'drupal/core-recommended:^10' --update-with-dependencies --no-update
composer.json has been updated
$ composer require 'drupal/core-composer-scaffold:^10' --update-with-dependencies --no-update
./composer.json has been updated
$ composer require 'drupal/core-project-message:^10' --update-with-dependencies --no-update
./composer.json has been updated

It is not recommended to have the package drupal/core-dev installed on a production site. If you have, remove it, or require that as well.

Update to the code base:

$ composer update
…

Update the database:

$ drush updb
…

You may need to add the isolation_level key to the project's settings.php:

$databases['default']['default'] = array (
  …
  'isolation_level' => 'READ COMMITTED',
  …
)

If the status report complains about the "SameSite cookie attribute" not being set, set it in the project's services.yml. If services.yml doesn't exist already, copy default.services.yml to services.yml. For background, see this CR: Drupal now defaults to "Lax" for the SameSite session cookie attribute.

Restore read-only access to relevant files and directories:

$ chmod 755 web/sites/default
$ chmod 644 web/sites/default/*settings.php
$ chmod 644 web/sites/default/*services.yml

Check version:

$ drush core-status --field=drupal-version
10.1.6

This procedure has so far worked OK for me for upgrading a dozen Drupal 9 webites to Drupal 10.

Sources on DO: Upgrading from Drupal 9 to Drupal 10, Overview, Upgrading a Composer-based-site.

CKEditor

After upgrading, "CKEditor" need to be restored as the Text editor for the formats "Full HTML" and "Basic HTML", and the Active toolbar restored. The illustration below show how it should be by default:

Default buttons to appear on the toolbar.

All headings except H1 should be enabled.

Troubleshooting

If there is a dependency on a earlier version of core, you may get this:

drupal/core-recommended 9.2.7 requires drupal/core 9.2.7 -> found drupal/core[9.2.7] but it \
  conflicts with your root composer.json require (^8.8.0).

Fix it be whitelisting a compatible version:

$ composer require 'drupal/core:^9' --update-with-dependencies --no-update
composer.json has been updated

If you have extensions installed, you may get this, even if all of them are upgraded to version that is supposed to be compatible:

$ composer update
Your requirements could not be resolved to an installable set of packages.
  Problem 1
  - …

You may uninstall and remove the problematic extension, but unmet dependencies will probably prevent you from doing so. If this hits you, you may go back to Drupal 8:

$ composer require 'drupal/core-recommended:^8' --update-with-dependencies --no-update
composer.json has been updated
$ composer require 'drupal/core-composer-scaffold:^8' --update-with-dependencies --no-update
./composer.json has been updated
$ composer require 'drupal/core-project-message:^8' --update-with-dependencies --no-update
./composer.json has been updated

You should now be able to uninstall and remove.

If any of the packages does not have a release explicitly declared as D9-compatible, you will likely run into a dependency error when trying to update your codebase. There may already be a patch in the issue queue that you can use if you use to upgrade the project to be Drupal 9 compatible. Please refer to this blog post by Damien McKenna for more details on how to handle this situation: How to Fix the Catch-22 Problem of Drupal 9 Fixes in Composer.

For trouble with the update data base step, see this DO Forum post.

[TBA]

Final word