The Drupal 10 upgrade is a structured operational engagement, not an ad-hoc change. For institutional Drupal sites (government agency portals, university public-facing sites, nonprofit program sites), the upgrade is a documented event that produces audit evidence and lands cleanly in production. This post is the catalog of best practices that institutional Drupal teams follow.
We covered the cost-of-inaction case in Drupal 10 Upgrade: Why Does Your Business Need It, the upgrade matrix from any source version in Upgrade to Drupal 10 From Any Version, and the early-adopter lessons in Upgrade to Drupal 10: Lessons From Early Adoption. This post focuses on the operational best practices.
Pre-Upgrade Best Practices
Before the upgrade work starts, the institutional team builds the foundation.
Confirm Drupal 9 currency. The site is on Drupal 9.4 or 9.5 (the supported migration source for Drupal 10). Sites on older Drupal 9 minor versions get to current Drupal 9 first as a separate operational step.
Audit the contrib module inventory. Use the Drupal Upgrade Status module to inventory active contrib and check Drupal 10 readiness. Modules without Drupal 10 releases get a remediation path: replace with an alternative, sponsor the contrib update, remove the dependency entirely, or accept the risk and plan for a contrib release post-upgrade.
Audit custom code with PHPStan. Run static analysis with PHP 8.1 as the target. Issues remediated before the upgrade starts. Custom modules with deprecated API calls flagged for refactor.
Audit theme with the Drupal 10 theme requirements. Custom themes built against pre-Drupal-10 patterns need remediation. Olivero is the reference theme; the institution's custom theme is updated to match the Drupal 10 theme APIs.
Confirm hosting platform PHP 8.1 readiness. PHP 8.1 minimum is required. Hosting platform team confirms PHP version availability and any platform-specific dependencies (e.g., specific PECL extensions).
Inventory institutional integrations. SSO, single-sign-on through institutional IdP, content syndication consumers, REST API consumers, search integrations, content authoring integrations. Each is documented with its expected behavior post-upgrade.
Establish staging that mirrors production. Same Drupal version, same contrib set, same custom code, same content sample, same hosting platform PHP version. The staging environment is the upgrade rehearsal stage.
In-Upgrade Best Practices
The upgrade itself follows a structured sequence on staging first, then production.
Document the change in change-control before starting. Change request, justification, validation plan, rollback plan, named approver, named executor. The documentation is the audit evidence.
Snapshot before starting. Database snapshot, filesystem snapshot, configuration snapshot. The snapshots are the rollback foundation.
Run the upgrade through Composer. composer require drupal/core-recommended:^10 (or the institution's equivalent), composer update, then run database updates with drush updatedb and rebuild caches with drush cache:rebuild. Each step produces a log; the logs are retained.
Validate the upgrade output. Smoke test the public-facing surface and the admin surface. Run the institutional integration tests. Validate the performance baseline against the pre-upgrade measurement.
Document any issues. Issues that surface during validation get documented with their resolution. If an issue cannot be resolved in the upgrade window, the rollback is exercised and the upgrade is rescheduled.
Promote to production after staging validation. Production upgrade follows the staging procedure exactly. Any deviation is a flag.
Post-Upgrade Best Practices
The upgrade is not done at production deploy. It is done after the observation period closes cleanly.
Establish an observation period. Typically two to four weeks of elevated monitoring after the production upgrade. During the observation period, the operations team is on standby for issue response, performance baseline is monitored against the pre-upgrade baseline, and stakeholder feedback channels are open.
Run the institutional integration tests. SSO flows, content syndication, REST API, search, content authoring. Validate that institutional integrations work as expected, not just that the Drupal site responds.
Re-baseline performance and security. Performance metrics post-upgrade compared to pre-upgrade baseline. Security scan post-upgrade compared to pre-upgrade scan. Any regressions remediated.
Update institutional documentation. System documentation, runbooks, training materials, and authorization-boundary documentation reflect the new Drupal version. The documentation update is part of the upgrade work, not a separate project.
Capture lessons learned. What went well, what was harder than expected, what would the team do differently for the next major version. The lessons-learned record informs the Drupal 10 to Drupal 11 upgrade planning.
Cross-Cutting Best Practices
Some practices apply across all phases.
Communication discipline. Stakeholders (institutional content team, internal users, external users) know when the upgrade happens, what to expect, and what to do if they encounter issues. The communication is in advance, not retrospective.
Single point of execution. The upgrade is executed by a named team or vendor with clear authority. Multiple teams executing different parts of the upgrade in parallel is operationally fragile.
Discipline in scope. The upgrade is just the upgrade. Combining the upgrade with major content changes, theme redesigns, or new integrations multiplies risk and obscures root cause if issues surface. Adjacent work happens before or after, not during.
Audit-ready evidence. Change-control records, validation logs, rollback exercise records, post-upgrade observation results. The evidence is retained for institutional audit retention period.
For managed Drupal hosting engagements supporting government and higher-education Drupal workloads, this best-practices catalog is the engagement structure. For institutions executing internally, the same catalog applies at the institution's operational depth.
What This Catalog Produces
When the best practices are followed:
Clean upgrade. Production upgrade lands without surprises. Issues that surface are minor and resolvable in the observation window.
Audit evidence. The institution can demonstrate the upgrade was executed deliberately, validated thoroughly, and documented properly. Audit conversations are about evidence, not about whether process exists.
Operational continuity. Institutional users (content authors, end users, integrators) experience the upgrade as planned, not as disruption.
Forward path established. The upgrade discipline that worked for Drupal 10 also works for Drupal 11 and beyond. The institutional team has the muscle memory.
The catalog is not unique to Drupal. Many practices apply across CMS upgrades (WordPress major version updates, Cascade publish-target changes), and the cross-platform discipline is what makes mature institutional WebOps look effortless from outside.
Frequently Asked Questions
How long does a typical institutional Drupal 9 to Drupal 10 upgrade engagement take end-to-end?
For institutions with current Drupal 9 and maintained contrib: 2 to 6 weeks from project start to post-observation closure. The engagement breaks down into roughly 1 week for pre-upgrade audit, 1 to 3 weeks for staging validation and remediation, 1 day for production cutover, and 2 to 4 weeks for observation. Sites with substantial customization or contrib gaps add weeks.
What is the most common cause of failed institutional Drupal upgrades?
Skipping the staging validation phase, or executing the staging validation in an environment that does not actually mirror production. The upgrade appears to succeed in staging but fails in production because staging did not exercise the institution-specific surfaces.
Should institutional Drupal upgrades be executed in-house or by a managed-services partner?
Both are valid. The decision depends on internal capacity. Institutions with dedicated Drupal expertise can execute in-house with the catalog as the playbook. Institutions without dedicated capacity benefit from a managed-services partner who has executed the catalog repeatedly.
How does this catalog change for the eventual Drupal 10 to Drupal 11 upgrade?
The catalog applies the same way. Drupal 11 (released in 2024) follows the same upgrade pattern as Drupal 10: contrib audit, custom code review, theme remediation, staging validation, production cutover, observation window. Institutions that executed Drupal 10 cleanly have the discipline ready for Drupal 11.