Simplifying Drupal Updates: A Structured Approach to Worry-Free Maintenance

Executive Summary: Regular Drupal updates are critical for site maintenance, but many organizations find them challenging. Drawing from nearly ten years of experience as a Technical Account Manager (TAM) at Acquia, this article presents a structured approach that transforms updates from a source of stress into a reliable process.

Introduction

In today's Drupal reality, updates are sometimes feared and time-consuming. Companies fear that they may cause more harm than good, which makes them difficult to run. The longer companies wait for updates, the more complicated an update can be.

The Drupal community has been working on new initiatives like the Project Browser (a UI tool for discovering and installing Drupal modules), which may provide a way to run updates in a Drupal site in the UI and potentially make them automatic. However, for sites that include development teams, partners, content creators, and other stakeholders, a structured process remains important.

General Considerations

Before diving into the two phases of update management, there are some general considerations to keep in mind:

First, it is important to understand that updates should be planned, executed by one person, and treated as a stand-alone task, meaning they are not done as part of a normal feature development task.

Second, companies should have a release procedure, which for some updates would include a hotfix procedure, so updates can be released immediately as needed, especially security updates.

It is important that when an update is executed, this process goes full circle. Full circle means starting the update process, going through all the necessary steps, and finally releasing the update to production, where it becomes part of the production code. This should be released and then communicated to the rest of the team, in that way the rest of the team can grab the update and see that it works with whatever they are working on.

The Two Phases of Update Management

When the site development is more than a hosted drupal, and includes a team of developers, partners, content creators, etc., it is important to develop best practices and procedures for your workflow, including drupal updates.

There are some specific parts to a Drupal update. Don't forget that all of this should be done in a local environment to be able to release this into the version control, or git repository.

Phase 1: Initial Setup

The first thing that needs to happen is having a well-maintained composer file. Some potential errors that may cause problems include:

1. There should not be any locked version packages in the constraints. For example, avoid specifying exact versions like drupal/module_name: 2.0.0 and instead use more flexible constraints like drupal/module_name: ^2.0
2. If using patches, it is very important to have a good inventory of these patches, and preferably use the URL to get the patch from GitLab in Drupal.org.
3. If using custom repositories, it is also important to maintain a good inventory of these. The goal is to avoid the big conflict message that composer gives when requiring a module or updating it.
4. If using a configuration management strategy, this needs to work correctly.

The main issue of conflicts with your composer constraints is that the message is never clear, and sometimes can be confusing. These conflicts are usually easier to fix one by one and require some amount of experience to navigate the errors and find out exactly what is really causing the issue. This is especially important when the package causing the conflict may be a package loaded as a requirement by another one. The best strategy to resolve conflicts, once the culprit is identified, is to update the specific packages that are causing the error before moving to the larger update.

It is also important to notice if there are new versions of modules, if the changes coming are minor versions or major versions, and if there is any special update process to follow, either from core or modules.

If the updates are running behind, it is better to move them forward slowly. The problem with this is that it will require hotfix releases on every step. Check the example in "Incremental Updates Approach"

Once the composer file is well maintained, updates are up to date, and we know what we have, updates may become just a repetitive task for the most part.

Before starting the update process, there may be some initial steps to organize everything so 90% of the updates become a simple composer update, drush updb, and drush cex process. From cleaning up your composer file to having a good config management process.

Incremental Updates Approach

If during the initial setup it becomes clear that some updates are way behind, the process should be to go step by step. For example, if you are in Drupal 10.1 and need to go to 11, you should go through the versions one by one.

Start by going to the latest 10.1.x, follow the process, deploy code to production and after that update is officially released, it is then when you can do the next step, the update to 10.2.x and, again, follow any upgrade recommendations you may find, Deploy and release. Only then is when you can do 10.3, and follow the same pattern, until finally you are able to do version 11.x.

This is just a rough example to explain the idea.

Phase 2: Maintenance Process

Every update process should occur using code and database versions that match production.

The standard update process includes:

1. Updating the code
   • Running composer update
   • For this to go smoothly it will require that the initial phase has been completed and composer.json is clean.
2. Database Updates
   • Running drush updb
   • Sometimes modules and core have updates that are run via hook updates, especially when there are major and mid-version changes, these can be an alarm to ensure that the configuration exports happen.
   • Monitoring update messages will help you understand if any major configuration changes happened.
3. Configuration Management
   • Running drush cex
   • Export configuration when needed, as mentioned in the previous step.
   • If Drupal core or modules updates have happened, there is a high possibility that you need to export configuration. This is important for cases where the configuration schema has changed and might cause later issues. Look at the "From the field" stories.
   • Remember in terms of configuration management, your code is the source of truth.
4. Custom Code Management
   • When major updates happen, you should be ready to update your custom code. It is advisable to have an inventory of the Drupal and module APIs in use and keep an eye on and follow Drupal change records.
   • SOmetimes modules and Drupal core may change the way an API works, failing to update this deprecated code may cause issues in the future. Read the "From the Field: API Changes" section for an example.
5. Testing and QA
   • Ideally, you should use tools to provide testing not only for your code but for your site behaviors. 
   • It is important to also have a good inventory of what QA can test, and probably use a tool like Nightwatch.js or any of the current tools for automated tests.
   • Both behavior tests and graphic regression tests could help make the process of releasing updates quicker.

From the Field: Configuration Schema Change

During a Drupal 10.1 to 10.2 update, a key was removed from the system.performance configuration, called 'stale_file_threshold'. When a customer did the upgrade but did not export configuration, once they deployed to production, Drupal did not know what to do with this key and produced an error.

What happened? The composer update updated Drupal core from 10.1 to 10.2. The database updates updated and deleted the key from the active configuration (database), by not exporting configuration, this key remained in the code.

After deployment and when the process of importing configuration ran, which should happen every time you deploy code, it brought the configuration entry back into the active config (we called the copy of the configuration in the code staged configuration). This caused all sites in a large multisite install to produce a 500 error because the site did not know what key stale_file_threshold was - "unknown configuration" was the error message in the logs.

Why This Matters: It is important to remember that the source of truth in configuration should be your code, not your database. If you don't export the changes that database update make to your active configuration, you open the door to a potential WSOD .

From the Field: API Changes

The issue arose from Form API changes that introduced a change in the way the storage variable of the Form object was used. Basically and in simple terms, this storage variable was moved. The customer had a module that used form API heavily. 

The module stopped working because while all the code was not producing any errors, they were storing their changes using the old storage location. While this never gave an error, these changes did not "mean" anything to Drupal and their module changes were never shown.

Why This Matters: By having an inventory of the code use for custom module and following the relevant change records for core in drupal.org, this type of issue can be prevented. 

Conclusion

When properly set up and followed, this structured approach transforms updates from a dreaded task into a routine maintenance process. The initial investment in proper setup and processes pays off in smoother, more reliable updates and reduced risk of site issues.