How we upgrade and modernise Drupal sites

If your organisation runs on Drupal, there is a fair chance you are not on the latest version.

Maybe you are on Drupal 7, which has reached end of life and no longer receives support or security fixes at all. Maybe you are on 9 or 10 and a newer major version has already landed.

Either way, you have probably been told the same thing more than once: you need to get current, and it is going to be a project.

The word "upgrade" hides a lot, though. Moving from Drupal 10 to the latest version is a very different exercise from moving off Drupal 7.

Some upgrades are a careful update of what you already have. Others are closer to rebuilding the foundations underneath you while keeping your content and features intact.

Knowing which one you are actually facing is the first real step, and it is where a surprising number of upgrade projects go wrong before they even begin.

Here is how we approach it, whatever version you are starting from.

First, work out what kind of upgrade this really is

Not all Drupal upgrades are the same shape, and the honest first move is to name which one is in front of you.

Drupal 8, 9, or 10 to the latest version. These are in-place upgrades. It is the same modern Drupal architecture underneath, so the work is bringing your code and your dependencies up to match the new version. You keep your site, your content, and your configuration, and you lift the whole thing to current.

Drupal 7 or older to modern Drupal. This is not an update, it is a migration. Drupal was rearchitected between 7 and 8, so an old site cannot simply be bumped forward. Instead we stand up a fresh modern Drupal build and move your content and configuration into it through Drupal's Migrate system. It is more work, but it is well-trodden work, and what you end up with is a genuinely modern platform rather than an old one wearing a new coat.

Both paths follow the same disciplined process. The difference sits mostly in the middle, where a version upgrade updates code in place and a migration carries content across into a new build.

The process we follow

A Drupal upgrade goes wrong when it is treated as one big leap into the unknown. We break it into ordered steps, each one testable, so at every point we know what has changed and that the site still works.

We assess before we touch anything

Every upgrade starts with an audit, because the worst thing you can do is discover the scope halfway through.

We go through the contributed modules and sort them into the ones that already have a version for the target release, the ones that have been abandoned and need replacing, and the ones you no longer need at all. We read the custom code for deprecated APIs that the new version will reject. We check the existing patches, the PHP version, and the parts of the site most likely to hold a surprise.

The output is a clear, honest picture of the work: what breaks, what has to be replaced, and how big the job genuinely is before anyone commits to it.

We get the foundation and dependencies current

With the scope known, we bring the groundwork up first: the PHP version, the Composer dependencies, and the build and deployment tooling.

We set the project up on Vortex(Opens in a new tab/window), our open-source Drupal project template, so it has a consistent and tested build, CI, and hosting configuration from the outset rather than something improvised per project.

Then we work through the contributed modules, updating each to a release that supports the target Drupal version, swapping out the abandoned ones for maintained alternatives, and re-rolling any patches the project relies on.

We modernise the custom code

This is where the version-specific work lives. Each Drupal release retires old ways of doing things and expects new ones: converting annotations to PHP attributes, updating hook and service signatures, adapting to the newer Symfony version underneath.

Much of this is mechanical but voluminous, and doing it by hand is slow and easy to get wrong. We lean on Rector(Opens in a new tab/window), a tool that understands the structure of the code and applies these upgrades automatically using rule sets built for each Drupal and PHP version.

It is not find and replace. It reads the code and rewrites it correctly, and every change it makes is verified by our tests.

We do the core upgrade, or the content migration

For an in-place upgrade, this is the point where Drupal core moves to the new major version and the whole site is retested against it.

For a Drupal 7 migration, this is where content types, fields, and configuration are mapped and moved into the new build through the Migrate system, piece by piece, until the new site holds everything the old one did and behaves the way people expect.

We test everything, automatically

None of the above is safe without a way to prove the site still works, and proving it by hand every time does not scale.

We cover the critical user journeys with Behat(Opens in a new tab/window), which describes what a user does rather than how the code is written, so those tests stay valid across the upgrade and confirm the site behaves the same after as before. Underneath, PHPUnit(Opens in a new tab/window) and static analysis with PHPStan(Opens in a new tab/window) guard the code at a finer grain.

All of it runs in continuous integration on every single change through GitHub Actions(Opens in a new tab/window), so a regression shows up within minutes instead of in front of a real user.

Before release, visual regression testing with Diffy(Opens in a new tab/window) compares the upgraded site against the current one screen by screen and flags anything that shifted, so a stray style change cannot slip through unnoticed.

We deploy with a safety net

The upgrade goes to a staging environment first for a full regression pass, then to production with a clear path back if anything unexpected appears.

By the time it reaches production it has already been validated many times over, so go-live is the calm part, not the frightening one.

The tooling that makes upgrades safe

Most of what makes a Drupal upgrade reliable is not heroics on the day. It is tooling we have built up and reused across many projects, so each new upgrade starts from a proven setup rather than a blank page.

Where AI fits

A well-tooled upgrade is also where AI earns its place, rather than being a gamble. The parts of an upgrade that AI is genuinely good at are the repetitive, well-defined ones: mechanical refactors repeated across many files, drafting test coverage, and working through a long migration of similar records.

It helps here precisely because the guardrails already exist. The tests and CI tell us within minutes whether something is wrong, so we get the speed without giving up control. We build instructions for AI agents into our project template so an agent understands how the project is put together before it changes anything.

What AI does not do is make the judgment calls. It does not decide the architecture, weigh the trade-offs, or own the result. We do that, and we review everything it produces. AI takes the friction out of the work. It does not replace the engineering.

After the upgrade

Getting to the latest version is the hard part. Staying there is not, as long as the tooling stays in place.

We leave Renovate watching the dependencies and CI checking every change, so updates keep flowing in and getting tested automatically. That is what keeps the next upgrade from becoming another large project years down the track.