Some tips for updating a manually installed Drupal 9 site to Drupal 10

I was hired recently by two companies to upgrade their Drupal-based websites from D9 to D10.

Both had in common that their sites weren’t controlled by Composer, but had been manually installed.

This is relevant to this post in 2 ways: 1) most online documentation assumes you use Composer and is therefore of limited use for the upgrade process if you are not using composer, and 2) a Composer upgrade may go wrong in ways that a manual upgrade does not and vice versa.

1) Read the Drupalize.me upgrade tutorial.

In the following I am going to assume you have read that document.

2) Drupal 10 is Drupal 9.5 with bits taken out.

That is still from the above document, but I am going to explain what that means.

What it means is that if you have upgraded everything as far as it goes in the D9 branch, and I do not just mean Drupal core, but also contrib modules, contrib themes, custom modules and custom themes, you are 90 % of the way there.

Upgrading everything means also upgrading contrib modules to a next major version that supports both D9 and D10 if the current version only works with D9. Upgrading to a major version may mean loss of functionality, so make sure that after all those upgrades the site still runs the way you like.

2a) The Metatag module pretends to not be upgradeable.

This is a known bug that has been solved in later versions.

3) Remove unused and uninstalled modules.

As in, uninstall and then remove the files. Drupal will try and read uninstalled modules, and D10 will definitely croak if it finds incompatible uninstalled modules.

4) Learn how to clear caches without a running Drupal install.

There are going to be conflicts between the cached database configuration and the actual code. They will lead to a down website. Being able to clear those caches and then log in and run the database scripts is important.

5) Learn where your PHP and/or web server error logs are.

Modern error messages can be confusingly woolly, but they typically at least give you some idea of which contrib module or theme is acting up.

If you forgot to upgrade a contrib module to a version that supports D10, now is when you will find out.

Error messages are great for googling. Often times you will be sent on a wild goose chase by people who don’t know either but who cannot avoid pretending they do, but sometimes you will find the solution.

6) Update custom themes.

One of the changes in D10 as compared to D9 is that it uses Twig 3 instead of Twig 2. In Twig 2 a number were also deprecated, so check your custom themes for these deprecated features.

If you are confident that your theme will work with D10, you can edit your *.info.yml file so that the core_version_requirement field lists ^10.

There probably are a lot more things that can go wrong and a lot more tips that can be given, but these are the ones I have for you.

If you can learn one thing from this post, learn that you should get your D9 install as close to D10 as you can before attempting the actual upgrade. Failing to do so will almost guarantee a broken site. An upgrade to D10 can be a lot of work, so it can be tempting to skip things. Drupal can unfortunately be pretty fragile at times, so a proper preparation is important.

This entry was posted on Friday, January 5th, 2024 at 1:43 pm and is filed under Web design + usability. You can follow any responses to this entry through the RSS feed. You can leave a response, or trackback from your own site.