deprecation-and-migration

Deprecate an API by first shipping a production-proven replacement, then announcing the deprecation with a migration guide and tooling. Migrate consumers incrementally using feature flags or the strangler pattern, and only remove the old API after metrics confirm zero active usage.

The strangler pattern runs old and new systems in parallel while routing traffic incrementally from old to new. You start with a small canary percentage, scale to full traffic on the new system, and remove the old system once it handles zero requests.

Use compulsory deprecation only when the old system has security issues, blocks progress, or has unsustainable maintenance cost. It requires a hard deadline plus migration tooling, documentation, and support; advisory deprecation is the default otherwise.

Zombie code with active consumers but no owner must either get an assigned maintainer or a concrete deprecation and migration plan. Leaving it unmaintained accumulates security vulnerabilities and compatibility debt.

Users rarely migrate on their own because of Hyrum's Law: they depend on undocumented behaviors the replacement may not replicate. The team owning the deprecated system must provide migration tooling, documentation, and incentives, or perform the migration themselves.