Treat a Drupal upgrade as a release, not a command

A successful Composer update proves that a set of packages can be resolved. It does not prove that custom code, configuration, content, and hosting work together. Treating an upgrade as a release makes the difference between a changed version number and a platform that is ready for its users.

Build an inventory before changing versions

Record the current core version, PHP runtime, contributed modules, custom extensions, patches, and hosting constraints. Check deprecated modules and unused dependencies. Confirm that a recent database backup and uploaded files can be restored. A database snapshot alone may not reproduce a site whose file storage has changed.

Validate the actual runtime

Run the upgrade in a representative environment using the intended PHP version and extensions. Review database updates and configuration changes separately. Exercise editorial forms, search, authentication, scheduled jobs, and integrations as well as public pages. Capture deprecation notices instead of treating a page that renders as sufficient evidence.

Keep the release reproducible

Commit the dependency lock file and use installation from that lock in deployment. Document the order of database updates, configuration import, cache rebuilding, and any content changes. Establish a recovery plan before release; restoring older code against a changed database may not be a valid rollback.

Build a release record before changing dependencies

Start a short record that names the target environment, the person coordinating the release, and the journeys that must continue to work. Include editorial tasks as well as visitor pages: signing in, editing a component, uploading an image, and submitting a form can reveal different problems. The record should link to the exact code and configuration being evaluated.

Review the site's custom extensions and integrations as a separate workstream. A dependency solver can select a compatible package set without proving that a custom form behaves correctly or that a scheduled integration still runs. Assign those checks to someone who understands the expected result. Capture unresolved findings rather than treating a successful installation as the end of validation.

Rehearse the sequence

Use an appropriate non-production copy to run the same sequence intended for release. Measure how long database updates and configuration changes take, and note any manual steps. Keep test messages inside the test environment. A rehearsal that sends real inquiries or alters live external records creates a second problem while trying to verify the first.

Ask the release operator to follow the written procedure without relying on its author to fill gaps from memory. If a credential, file location, or permission is missing, fix the procedure and repeat the affected step. Record what the application looks like after each critical phase so an unexpected result is recognizable.

Define recovery before the release window

Recovery needs a consistent combination of code, database, configuration, and files. Identify what changes after the backup and how those changes would be handled if recovery became necessary. Do not assume that switching a code reference also reverses database changes. Give the person making the recovery decision a clear stop condition and an agreed communication route.

After release, repeat the priority journeys, inspect operational signals, and confirm that queued or scheduled work is progressing. Retain the release record with the observed result. The next upgrade becomes easier when the team has a concrete account of what happened rather than a collection of terminal commands.

A practical next step

Write a short release checklist covering one anonymous journey, one editor journey, a key integration, and a restore procedure. Run it on the upgrade environment and record the results alongside the code change.