Planning a Drupal Major Upgrade: A Checklist Before You Start

A Drupal major upgrade is one of the few website projects where the work you do before touching anything decides whether the project takes a weekend or a quarter. Sites that jump straight to the update command discover their blockers at the worst possible moment — a contributed module with no compatible release, a hosting plan that cannot run the new version's requirements, a theme built on an API that no longer exists. Sites that plan first meet the same blockers in week one, on a copy, with time to route around them. This checklist is the planning pass: readiness checks, module audit, and a staging rehearsal that turns upgrade day from an expedition into an errand.

The checklist assumes you already know why Drupal is the right platform — the Drupal Commerce vs Shopify for custom business workflows discussion covers that decision — and focuses on the operational run-up. It also assumes the routine work around your site matters: your configuring Drupal cron jobs with crontab configuration and your how to install Drush setup must both survive the upgrade, and the Drush short tips habits are what make the rehearsal repeatable. Follow the official upgrade path documentation at drupal.org's upgrading guide as the canonical reference alongside this checklist.

Why Planning Outranks The Upgrade Itself

Major version upgrades fail in predictable places, and almost none of them are the upgrade command. The failures are inventory failures: a dependency nobody remembered, a custom module written against an API that changed, an integration — payment, search, mailing — that only reveals its coupling when it stops working. Each of these is cheap to discover in a planning document and expensive to discover mid-migration. Planning also buys negotiating room: if the module audit shows one blocker module with no compatible release, you can schedule a replacement or a custom patch before the upgrade window exists, rather than discovering it with the site half-migrated. The rule worth writing on the wall: the upgrade is the last ten percent of an upgrade project, and the first ninety percent is everything on this checklist. Teams that internalize that stop treating planning as optional caution and start treating it as the actual project.

Readiness Checks First

Begin with the environment, because it eliminates whole categories of surprise. Confirm the hosting stack meets the target version's requirements — PHP version, database version, memory limits — and ask the host directly rather than assuming the control panel tells the truth. Audit custom code: list every custom module and theme, and for each one identify which APIs it touches; anything leaning on deprecated services from two major versions ago is a candidate for rewrite before migration, not after. Review integrations one by one — payment gateways, search services, CRM hooks, analytics — and classify each as compatible, needs-configuration, or unknown. Finally, freeze the scope: decide what will not change during the upgrade window, because a migration combined with a redesign or a content restructure is not a project, it is three projects sharing one failure. This pass typically fits on two pages, and those two pages are the difference between a rehearsal that finds real issues and a surprise that finds you.

One readiness item deserves emphasis because it is the most skipped: the content freeze decision. Decide explicitly what happens to editorial work during the upgrade window — usually a full freeze, occasionally a narrow exception for time-critical content — and write the decision next to the timeline, because an unwritten freeze is a freeze that gets violated at the worst moment, usually by someone with the best intentions.

The Module Audit

The module audit deserves its own pass because contributed modules are where most upgrades live or die. Export the full module list from the current site and sort it into four buckets. Bucket one: modules with stable releases for the target version — no action beyond noting the version to install. Bucket two: modules with development or beta releases — schedule testing time, because these work but may have rough edges. Bucket three: modules with no compatible release — this bucket drives the project timeline; for each entry decide whether to replace, retire the feature, or commission a port, and price that decision in days, not vibes. Bucket four: modules nobody can explain — uninstall candidates, because a major upgrade is the one legitimate moment to delete what the site no longer needs. While auditing, check each module's maintenance health: last commit date, open issues against the target version, maintainer responsiveness. A module technically compatible but abandoned is bucket-three risk wearing a bucket-one costume, and it deserves the same scrutiny as an outright incompatibility.

The audit also produces a side benefit that pays off during the rehearsal: a clean module list is a fast module list. Sites that arrive at an upgrade carrying years of unused modules pay for them twice — once in audit time, and again in rehearsal time as each questionable module gets investigated. Sites that have pruned along the way find the audit takes an afternoon, because the honest list of what the site actually uses is short and well-remembered. Treat the audit as the forcing function for that pruning: anything that survives three audits without a defender is a candidate for retirement before the next one, and a leaner module list is itself an upgrade-risk reduction, independent of the version number being targeted.

The Staging Rehearsal Plan

Never rehearse on production; that is what staging is for. Clone the site to a staging environment with production data, run the full upgrade there first, and time every step — the timings become the upgrade-day runbook. After the rehearsal boots, run a smoke pass over the things that matter: content editing, user login and registration if applicable, the cron queue actually processing, search, any forms, and the integrations from the readiness audit. Rehearse the rollback too, at least at the level of "we restore last night's backup and re-point DNS," because a rollback path that has never been stated is a hope. Between the rehearsal and the real run, write the runbook: ordered steps, expected durations, the go/no-go criteria, and who is watching which channel if something goes sideways. If the rehearsal surfaced fixes, apply them and rehearse once more — the second rehearsal is usually the one that runs clean, and it is cheap compared to a failed production attempt.

Finally, decide who is in the room before the room exists. Name the person running the runbook, the person watching for breakage, and the person authorized to call the rollback — three roles, sometimes two people, occasionally one very calm person wearing two hats. Upgrade-day confusion is rarely technical; it is the confusion of five people asking "should we stop?" with no designated answerer. Writing the roles into the runbook takes one line and removes the most common human failure mode from the entire project.

The Planning Checklist At A Glance

Three passes, three outputs — and every output exists before production is touched. That is the entire shape of a well-planned upgrade.

The Failure Modes Planning Prevents

Each classic upgrade disaster maps to a skipped line on this checklist. The half-migrated site with a dead payment flow maps to the integrations review. The upgrade that took six weeks instead of two maps to the bucket-three module decisions made mid-flight instead of in advance. The site restored from backup at midnight maps to a missing rollback rehearsal. And the quietest failure — the upgrade that technically succeeded but left a cron queue and a Drush setup subtly broken — maps to forgetting that operational routines like configuring Drupal cron jobs with crontab must be re-verified, not just assumed. None of these require heroics to prevent; they require the unglamorous discipline of a planning pass done while nothing is on fire. Do the checklist on a calm schedule, keep the drupal.org documentation close, and the major upgrade becomes what it should have been all along: a planned project with a boring ending — which, in upgrade work, is the highest compliment available.