Skip to content

Upgrading from Drupal 9 to 10

Jump to bottom
Finn Lewis edited this page Jun 14, 2024 · 18 revisions

The Drupal 9 to 10 upgrade involves moving from LocalGov Drupal version 2.x to 3.x.

If you're using LocalGov Drupal without many modifications then upgrading should be as easy. If you've lots of additional contrib modules and/or custom code in modules or themes, then upgrading the LocalGov part of the site should be straightforward, but you'll need to go check that all your additional code supports Drupal 10 before you can upgrade.

Upgrade Status

The Upgrade Status module will help determine what needs to be done before you can upgrade to Drupal 10.

Before installing Upgrade Status, you might need to update the phpstan packages to supported versions.

composer require mglaman/phpstan-drupal:^1.0 phpstan/phpstan:^1.0 phpstan/phpstan-deprecation-rules:^1.0 --dev

Then install upgrade status.

composer require 'drupal/upgrade_status:^4.0'

Preparing your Drupal 9 site

Before you can upgrade to Drupal 10 you'll need to uninstall any modules that have been removed from Drupal core or install the contrib versions of these. The two modules used by LocalGov Drupal that are being remove are CKEditor and Quick Edit.

CKEditor 4 has been replaced by CKEditor 5. To prepare your site you should enable the CKEditor 5 module, migrate any text formats using CKEditor and then uninstall CKEditor 4. For more information see https://www.drupal.org/node/3223395#s-how-to-upgrade-fromckeditor-4-to-ckeditor-5

Quick Edit should be uninstalled. If you use this functionality there's a Quick Edit contrib module you can install in it's place.

Upgrade to the latest version of LocalGov Drupal 2 and ensure the localgov_geo_update module has been enabled

As part of the upgrade LocalGov Geo entities are migrated to Geo Entity entities. To do this you'll need to be running the latest version of LocalGov Drupal 2. When updating the localgov_geo_update module should be enabled, but it's a good idea to confirm this.

composer update localgovdrupal/* --with-dependencies
drush updatedb
drush cr
drush en localgov_geo_update
drush cr

Pleas also see release notes for localgov_geo https://github.com/localgovdrupal/localgov_geo/releases/tag/2.0.0

If you have the config_inspector module installed you can either remove this with composer remove drupal/config_inspector (it's been removed in LocalGov Drupal 3) or upgrade to version 2 with

composer require drupal/config_inspector:^2.0

Basic upgrade to Drupal 10 for LocalGov Drupal

The basic steps to upgrading to Drupal 10 involve installing the required LocalGov 3 and Drupal 10 packages using Composer and then running the Drupal database upgrades.

This will go something like:

composer require localgovdrupal/localgov:^3.0@alpha --update-with-dependencies --no-update
composer require drupal/core-recommended:^10.2 drupal/core-composer-scaffold:^10.2 drupal/core-project-message:^10.2 --update-with-dependencies --no-update
composer require drupal/core-dev:^10.2 --dev --update-with-dependencies --no-update
composer update
composer require drupal/geofield_map
drush updatedb

You can update your Location (Geo) form configuration to remove the dependency on Geofield Map. This is the default for new installs, and is why Geofield Map is no longer an included dependency.

Basic upgrade to Drupal 10 for LocalGov Microsites

0. Check you are using PHP 8.2

Make sure you are running PHP 8.2 before starting the upgrade.

If using the stock .lando.dist.yml from the localgov_microsites_project, you might need edit that file to specify PHP 8.2:

config:
  xdebug: false
  webroot: web
  php: '8.2'

It is also important to make sure to tell Lando to use the system composer, rather than that supplied in vendor.

Under the tooling section of .lando.dist.yml or .lando.yml:

tooling:
  composer:
    service: appserver
    cmd: /usr/local/bin/composer

Then do a lando rebuild.

lando rebuild

Note: If using lando, you can shell into the lando docker container to make sure to run with the correct php and composer versions;

lando ssh

The rest of the commands below assume you are inside the docker container, or on your local system running the website.

1. update all LocalGov Drupal packages:

composer update localgovdrupal/* --with-dependencies
drush updb

2. Install upgrade status and check report.

composer require drupal/upgrade_status -W
drush en upgrade_status -y

3. Uninstall deprecated modules

If installed, uninstall Quick Edit and CKeditor 4 (see above).

drush pm:uninstall quickedit ckeditor

Check the Upgrade Status report for other deprecated modules.

4. Check repositories in composer.json.

Check the site's composer.json to confirm it has the correct repository settings.

The repository section of the site's composer.json file should look like:

    "repositories": {
        "drupal": {
            "type": "composer",
            "url": "https://packages.drupal.org/8",
            "exclude": ["drupal/domain_group", "drupal/group_permissions"]
        },
        "drupal/domain_group": {
            "type": "vcs",
            "url": "https://git.drupalcode.org/project/domain_group.git"
        },
        "drupal/group_permissions": {
          "type": "vcs",
          "url": "https://git.drupalcode.org/project/group_permissions.git"
        }
    },

Some older sites will have a different entry for drupal/domain_group.

For an example see the project's composer file: https://github.com/localgovdrupal/localgov_microsites_project/blob/3.x/composer.json

5. Update codebase with composer.

composer require localgovdrupal/localgov_microsites:^3.0@alpha --update-with-dependencies --no-update
composer require drupal/core-recommended:^10.2 drupal/core-composer-scaffold:^10.2 drupal/core-project-message:^10.2 --update-with-dependencies --no-update
composer require drupal/core-dev:^10.2 --dev --update-with-dependencies --no-update
composer require drush/drush:^12 --update-with-dependencies --no-update
composer require 'drupal/geocoder:^4.23' --update-with-dependencies --no-update
composer update
drush updatedb

Note: if using lando, and you have composer errors with the above shelled into the docker container, you might be better running the composer commands from the host machine with:

lando composer require localgovdrupal/localgov_microsites:^3.0@alpha --update-with-dependencies --no-update
lando composer require drupal/core-recommended:^10.2 drupal/core-composer-scaffold:^10.2 drupal/core-project-message:^10.2 --update-with-dependencies --no-update
lando composer require drupal/core-dev:^10.2 --dev --update-with-dependencies --no-update
lando composer require drush/drush:^12 --update-with-dependencies --no-update
lando composer require 'drupal/geocoder:^4.23' --update-with-dependencies --no-update
lando composer update
lando drush updatedb
Clone this wiki locally