Rolling deploys follow expand-migrate-contract phases with an explicit mixed-version compatibility window and rollback rules so old and new binaries coexist safely during schema and API changes.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Zero-downtime delivery is modeled as parallel change: expand the platform to accept both old and new behavior, migrate traffic and data while mixed versions run, then contract by removing obsolete paths only after the compatibility window closes. Each release declares which API and schema capabilities are safe across the mixed-version interval and how rollback behaves if a new binary is reverted while migrations already ran forward. Rollback never assumes a single atomic flip; it defines which mixed states are supported and for how long.
Scope
- Release phase gates: expand, migrate, contract.
- Mixed-version matrix for API readers/writers and database schema level.
- Rollback window policy when new code is pulled back but expand-phase artifacts remain.
- Traffic shift coordination with health gates during migrate.
- Operator runbooks for stuck mixed-version states.
Outside this block
- Container build and registry promotion mechanics.
- Feature-flag product semantics beyond deployment gating.
- Full disaster recovery of lost regions.
Contract
- Every deployable artifact declares its minimum compatible schema generation and peer binary version range before promotion.
- Expand phase must complete before migrate traffic increases above the profile threshold.
- Old binaries in the window must tolerate new nullable schema and unknown fields per the matrix.
- New binaries must read old rows and write dual-compatible shapes until contract phase starts.
- Contract phase runs only when mixed-version error rate and backlog metrics stay within budget.
- Rollback to the previous binary remains supported throughout the declared rollback window even after partial migrate.
- After rollback window expiry, forward-only migrations require explicit operator approval and documented recovery.
Implementation guidance
- Encode compatibility matrix entries as versioned configuration consumed by deploy orchestration.
- Use additive schema migrations in expand; destructive drops only in contract.
- Emit deploy phase metric labels so dashboards show expand/migrate/contract per environment.
Failure handling and safeguards
- If migrate error rate exceeds abort threshold, halt traffic shift and keep expand paths active.
- Never run irreversible data transforms while old binaries still receive production traffic above zero percent.
- Mixed-version intervals have a maximum duration; exceeding it pages release owners.
Verification and operations
- Measure mixed-version duration, rollback drills, schema generation skew, and incompatible-request rate.
- Game-day rollback with migrations partially applied must succeed within the rollback window definition.
- Execute acceptance scenarios in the target repository; packaged scenarios are not executed evidence.
Adoption assumptions
- Values in
example.yamlandcompatibility-matrix.yamlare profile choices, not universal defaults. - Teams map version identifiers, traffic controllers, and migration tooling locally.