deprecation-and-migration

Deprecate an API by first shipping a production-proven replacement, then announcing with a migration guide and concrete steps. 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 with tooling and support.

Migrate users incrementally, one consumer at a time: identify touchpoints, update to the replacement, verify behavior with tests, and remove old references. Use an adapter that translates the old interface to the new implementation, or feature flags to switch consumers gradually.

Remove legacy code when it no longer provides unique value, a replacement covers all critical use cases, and migration cost is lower than ongoing maintenance over two to three years. Code is a liability with continuous costs for tests, security patches, and onboarding.

Zombie code is unmaintained code with no owner but active consumers, often showing no commits in six months and unpatched vulnerable dependencies. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan; it cannot stay in limbo.