How to Upgrade a Major Dependency Without a Maintenance Window

Off-hours deployment reduces how many users notice a problem, but it doesn't reduce the risk of the migration itself, and it adds a nasty side effect: your quietest traffic period is also the one where a subtle bug is least likely to surface before it's rolled out everywhere. A change that behaves fine under low load can fall over hours later once real daytime traffic hits it.

Treat off-hours timing as a courtesy to your users, not a safety mechanism. The actual safety comes from how the migration is sequenced, not when the clock says it happened.

Expand-contract breaks a breaking change into three steps that are each individually safe to deploy and roll back. First, expand: add the new column, endpoint, or field alongside the old one, so both exist at once. Second, migrate: move reads and writes over to the new path while the old one still works as a fallback. Third, contract: remove the old path only once nothing is using it anymore, verified by actual traffic data, not by assumption.

The unglamorous part is that step three often gets skipped, leaving two versions of everything live indefinitely. Put a date and an owner on the contract step when you plan the migration, not just on the expand step.

The expand-contract pattern runs in three safe steps:

1. Expand: add the new column, endpoint or field alongside the old one, so both versions work at the same time.
2. Migrate: move readers and writers to the new version gradually, keeping each deploy small and easy to roll back.
3. Contract: once every consumer has moved and error rates stay flat, remove the old path instead of leaving it live.

Teams in DORA's top-performing cluster, the ones with the highest deployment frequency, tend to treat a version migration as a series of small, reversible deploys rather than one big cutover; teams whose deployment frequency is much lower¹ default to big-bang migrations because that's the only rhythm they know, and building a gradual rollout muscle for the first time in the middle of a risky migration is a bad place to learn it.

Running both versions at once means routing a small, controlled slice of traffic to the new path first, watching error rates and latency against the old path's baseline, and only widening that slice once the new path has proven itself under real conditions, not synthetic tests. Decide in advance what "proven itself" means, specific error-rate and latency thresholds, so widening the rollout is a decision made from a plan and not a gut call under pressure.

Every migration plan has a rollback step written down. Far fewer teams have actually executed it before they need it for real. A rollback that only exists on paper often turns out to be one-way in practice, because the new version already wrote data in a shape the old version can't read.

Before you start migrating real traffic, run the rollback deliberately against a copy of production data and confirm the old version still functions correctly against anything the new version wrote during the migration window. If it can't, your rollback plan is fiction.

When the change spans several services, order matters more than speed. Migrate the service with the fewest dependents first, so a mistake there has the smallest blast radius, and hold off on migrating anything that other unmigrated services still depend on directly. Trying to move everything in one release just recreates the big-bang problem you were avoiding, spread across more teams instead of contained to one.

Keep a simple, shared tracking document of which services are on the old version, which are on the new one, and which are mid-migration, so nobody accidentally builds a new feature against a path that's about to be removed. This sounds like overhead until the first time it prevents a team from shipping against a dependency that was scheduled for removal that same week.