deprecation-and-migration

Deprecate a legacy API by first building a production-proven replacement, then publishing a deprecation notice with a migration guide. Migrate consumers incrementally using the Strangler pattern or feature flags, and verify zero active usage via metrics and logs before removing the old code.

Advisory deprecation makes migration optional using warnings and documentation while the old system remains stable. Compulsory deprecation sets a hard removal deadline and is reserved for security risks or unsustainable maintenance cost, but requires providing migration tooling and support.

Use the Strangler pattern to route traffic gradually from old to new, an Adapter to translate old interfaces onto the new implementation, or feature flags to switch consumers one at a time. Verify behavior matches at each step before removing old references.

Remove zombie code when it has no owner, no commits in over six months, failing tests, or unpatched vulnerable dependencies, yet still has active consumers. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan.

Deprecations fail when announced without a working replacement, migration tooling, or documentation, because users cannot switch on their own. Hyrum's Law means consumers depend on undocumented behaviors, so owners must actively migrate users or provide backward-compatible updates.