deprecation-and-migration

Deprecate an API by first shipping a production-proven replacement, then announcing the deprecation with a migration guide and concrete steps. Migrate consumers incrementally using the Strangler Pattern or feature flags, and verify zero active usage through metrics and logs before removing the old code.

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 migration tooling.

Use the Strangler Pattern when old and new systems can run in parallel. Route traffic incrementally from old to new (0%, 10%, 50%, 100%), then remove the old system once it handles zero traffic, minimizing risk per migration step.

Zombie code is unmaintained code with no owner that still has active consumers, often showing no commits in 6+ months and unpatched vulnerable dependencies. Either assign an owner and maintain it properly, or deprecate it 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 ongoing maintenance cost. Build and prove the replacement in production before announcing any deprecation.