deprecation-and-migration

Deprecate an API by first shipping a production-proven replacement, then publishing a deprecation notice with a migration guide. Migrate consumers incrementally using the strangler pattern or feature flags, 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. Advisory deprecation is the default; a hard deadline requires providing migration tooling, documentation, and support.

Use the adapter pattern: create a class that keeps the old interface but delegates calls to the new implementation. Consumers keep working unchanged while you migrate the backend, then you remove the adapter once all consumers switch.

Zombie code is unmaintained code with no owner that still has active consumers, often shown by stale commits, failing tests, and unpatched vulnerabilities. It must either get an assigned owner and proper maintenance, or be deprecated with a concrete migration plan.

Do not deprecate when the system still provides unique value, when no working replacement exists, or when migration cost clearly exceeds the long-term maintenance cost. Deprecating without a proven alternative leaves consumers stranded.