deprecation-and-migration

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

The strangler pattern runs old and new systems in parallel while routing traffic incrementally from old to new, typically moving from 0% to a 10% canary, then 50%, then 100%. Once the old system handles no traffic, it is removed.

Use compulsory deprecation only when the old system has security issues, blocks progress, or has unsustainable maintenance cost. Advisory deprecation with warnings and documentation is the default, and compulsory removal requires providing migration tooling and support.

Use the adapter pattern to translate calls from the old interface to the new implementation, so consumers keep their existing code while the backend changes. Alternatively, gate the switch behind a feature flag and migrate consumers one at a time.

Zombie code is unmaintained code with no owner that still has active consumers, often showing no commits in 6+ months and unpatched vulnerable dependencies. It must either be assigned an owner and maintained properly, or 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.