Lessons from the Drupal 11 upgrade

The GovCMS upgrade to Drupal 11 (D11) is done.

And dev teams across Government can all attest to the fact that it was a lot of work.

It was so much more than a version bump and was probably closer to a dependency and architecture clean-up that was disguised as an ‘upgrade’.

Here’s what we learned after preparing 21 GovCMS sites, and what we’ll be advising clients for future upgrades.

Lesson 1. Invest early in a ruthless inventory and categorisation pass

The real blockers are usually invisible… until you properly audit your components.

It is critical to allocate enough time upfront to do a thorough inventory of the site.

Doing this helps your teams understand:

• What modules exist
• How modules and themes are currently used
• What modules you have that will not be supported

It’s critical groundwork that helps you avoid mid-project surprises. Think of it as a deep spring clean with much higher stakes.

Lesson 2. Use Visual Regression Testing (VRT) to make QA a whole lot faster

Visual Regression Testing (VRT) was an absolute timesaver!

It was a quick, easy way to spot if updates created visual inconsistencies or unwanted anomalies.

This reduced some of the manual effort involved in testing and really sped up the process for us.

One bonus and surprising benefit of VRT was it served as a quick way to support with user acceptance testing (UAT). We noticed a few times, business stakeholders would find bugs, like content not syncing or forms not loading, that had nothing to do with the website build. VRT made it easier to separate upgrade-related issues with other technical ones.

Lesson 3. Allocate extra time if your site uses role-driven or condition-driven access

The sites that were the trickiest to prep for were ones that had role-driven or condition-driven access.

These are sites that require users to log into and serve different content to different user roles. For example: An education website where students log in and see different content compared to teachers.

We found these sites would often break in subtle ways after refactors. Especially if the site was using deprecated modules Page Manager or GovCMS8 layouts.

We’d see issues with:

• Visibility being blocked and issues with page-level access
• Editorial preview behaviours
• Unpublished content behaviours
• Modules working for admin role, but not real ones

In future, sites that fit into this category, may need to allocate more time towards planning and QA testing. This involves thoroughly mapping out user flows, user roles and defining a clear test matrix upfront.

Lesson 4. Include ongoing maintenance in your site budget next time

A lesson for next time is the importance of ongoing maintenance.

‘Sustainment’ is rarely considered when budgeting a website build. We saw the impact of this firsthand in the form of woefully outdated website themes and NPM packages (the tools that compile and bundle your site’s styles and scripts during development.)

You can’t have a ‘set and forget’ mentality towards themes. All software has security implications and needs to be reviewed regularly.

So, allocate budget towards ongoing maintenance. Even a small amount budgeted over a 3-year lifecycle can go a long way.

This helps you avoid scenarios like needing to do major NPM upgrades or potentially even rebuilding components from scratch. Both of which are infinitely more time-consuming and costly.

Lesson 5. For future build or rebuilds, strive to be standard

The easiest sites to prep for the upgrade were the ones that used repeatable, standardised modules and templates.

When you implement in this way, you’re futureproofing your site and making it easier to manage and maintain.

For future builds or a rebuild, aim to:

• Use standard patterns
• Apply these repeatedly
• Document it once
• Reuse it everywhere

When it comes to website maintenance, it’s ok to be standard over cool and complex.

And while, yes, there are scenarios where customised and bespoke features are worthwhile. Just make sure you’re really weighing up the benefits with the cost of ongoing maintenance and sustainment.

It pays to plan ahead

Our biggest takeaway?

Like with any major upgrade, it pays to plan thoroughly and have a structured and methodical approach.

It’s certainly the approach we’ll be taking when D12 drops for GovCMS!