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.

Advisory deprecation uses warnings and documentation so users migrate on their own timeline, while compulsory deprecation sets a hard removal deadline. Default to advisory; use compulsory only when security risk or maintenance cost justifies forcing migration, and always provide tooling and support.

Migrate users incrementally, one consumer at a time: identify touchpoints, switch to the replacement, verify behavior with tests, and remove old references. Patterns like the Strangler approach, interface adapters, and feature flags let you shift traffic gradually instead of all at once.

Deprecate code when it no longer provides unique value, a working replacement exists, and the long-term maintenance cost exceeds the one-time migration cost. Compare migration effort against two to three years of ongoing maintenance, security patching, and onboarding overhead.

Zombie code is unmaintained code with no owner that still has active consumers, often showing stale dependencies and failing tests. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan; leaving it in limbo accumulates security and compatibility risk.