Backward-Compatibility Review Checklist
A review checklist for backward-compatible changes to APIs, services, and schemas. It enforces additive change, contract testing, expand-and-contract migration, and deprecation discipline.
When to Use This Checklist
Use this checklist before shipping a change to a service, API, or data schema that other systems depend on. Backward compatibility means existing consumers keep working without modification after your change deploys. In distributed systems, old and new versions almost always run side by side during a rollout, so incompatible changes cause outages even with perfect code.
How to Use This Checklist
Start by identifying every consumer and the contract version it relies on. The core rule is additive change: add optional fields, never remove or rename existing ones, and keep enum and type changes additive. Apply the expand-and-contract pattern for schema evolution: add the new shape, migrate consumers, then remove the old shape only after nothing uses it. Run consumer-driven contract tests to prove compatibility.
When a breaking change is unavoidable, version explicitly and give a deprecation period with clear notice.
What Good Looks Like
A compatible change adds only optional fields, keeps existing names and types intact, and passes consumer-driven contract tests. Database migrations are additive first, with column drops deferred until consumers stop reading them. Rolling deployments with mixed versions are tested. Any removal has a deprecation window and affected teams are notified.
Common Pitfalls
The classic break is removing or renaming a field that a consumer still reads. Teams forget that during a rollout, old and new code run together, so a non-additive schema change breaks the old version. Required new fields with no default reject older clients. Dropping a database column before consumers migrate causes errors.
Related Resources
See api-backward-compatibility and the expand-and-contract pattern for safe evolution, contract-driven development with Pact for verification, and schema evolution with a schema registry for messaging. Stripe's API versioning policy is a strong real-world reference.