backward-compatibility-and-deprecation-policy

Backward Compatibility and Deprecation Policy

This skill is about the process of retiring something that already shipped — the timeline, the communication, the enforcement mechanism. The question of how to design a contract so it doesn't need this process as often (additive changes, versioning, error-shape consistency) is covered by the api-design skill; read that one when you're designing the contract itself, this one when you're retiring something already in use.

Hyrum's Law sets the baseline expectation

"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody." (Hyrum Wright, popularized via the Software Engineering at Google book)

This means: the deprecation process has to assume real callers depend on behavior you never intended to guarantee, not just the documented contract. A deprecation plan built only around "we announced it in the changelog" underestimates how many callers won't see that changelog before their integration breaks.

Procedure: deprecating something already in production use

1. Determine actual usage before announcing anything. Instrument the old path (a log line, a metric counter, a response header) so you know who's still calling it — announcing a sunset date for something with unknown callers is how outages happen. If you can't measure usage, that's the first gap to close, not a reason to skip measurement.
2. Publish the deprecation with three concrete pieces of information: what's being replaced, what to migrate to, and a specific sunset date — "this will be removed eventually" is not a deprecation notice, it's a warning with no actionable deadline.
3. Mark it as deprecated in the artifact itself, not only in documentation: a Deprecation HTTP response header, a compiler deprecation annotation (// Deprecated: Go doc comment, @deprecated in other ecosystems), a CLI flag that prints a warning when used. Documentation-only deprecation is invisible to someone who never reads docs but does read a warning printed in front of them.
4. Give a grace period sized to your actual caller population and their release cadence — an internal API consumed only by services your own team deploys weekly needs a much shorter window than a public API consumed by third parties who batch their own dependency upgrades quarterly or yearly.
5. Track migration progress actively, don't just wait for the sunset date — if usage of the old path hasn't dropped as the date approaches, that's a signal to reach out to remaining callers directly (for internal APIs) or extend the deadline with clear justification (for public ones), not to remove it on schedule regardless.
6. Remove on schedule once usage is at or near zero, with a final direct check immediately before removal — don't let "we announced it months ago" substitute for confirming actual current usage is gone.