deprecation-and-migration

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

Use the Strangler Pattern to route traffic gradually from old to new, or feature flags to switch consumers one at a time. An Adapter Pattern can also translate old interface calls to the new implementation so consumers migrate without code changes.

Deprecate when the system no longer provides unique value, a replacement exists, and migration cost is lower than ongoing maintenance over two to three years. Code with no owner, failing tests, and unpatched vulnerabilities is zombie code that needs either investment or removal.

Users rarely migrate on their own because of Hyrum's Law: they depend on undocumented behaviors the replacement may not replicate. The Churn Rule states the infrastructure owner is responsible for migrating users or providing backward-compatible updates, tooling, and documentation.