How to coordinate Python API, worker and schema changes when versions overlap, clients lag and messages outlive the deployment that created them.
Design for overlap: old clients, old workers, new workers and queued messages must coexist long enough for the release to become safe.
List the versions that overlap
Rolling deployments create a mixed fleet. Mobile and external clients can lag for months. Queued messages may outlive both. Write down which versions can send and receive each contract before changing it.
A field that is optional in one direction may still be required by an older consumer. Compatibility matrices make these assumptions reviewable instead of hiding them in deployment timing.
Prefer additive transitions
Add a field before requiring it, accept both representations while migration runs and remove old behaviour only after telemetry shows it is unused. For messages, version the envelope or keep readers tolerant of unknown fields.
Do not use a feature flag as a substitute for schema compatibility. Flags control behaviour; they do not make an old binary understand a removed column or message shape.
Verify the transition
Contract tests should run old and new readers against representative payloads. Deployment rehearsals should exercise queued work, rollback and a client that has not upgraded yet.
Track deprecation usage and set an owner and removal date. Compatibility without an end state becomes permanent branching and untested code paths.
Evidence to take into review
- Overlapping client, worker and schema versions are documented.
- Changes use additive or explicitly versioned transitions.
- Old and new readers are tested against shared examples.
- Rollback and queued-message behaviour are rehearsed.
- Deprecated paths have usage telemetry and an owner.
Explore all engineering notes.
Use PRODUCTION-7 to connect this concern with the other dimensions of a trustworthy backend.
View all articles Get the checklist