deprecation-and-migration

Deprecate safely by first building a production-proven replacement, then announcing the deprecation with a migration guide, migrating consumers incrementally, and verifying zero active usage via metrics and logs before removing the old code. Never deprecate without an available alternative.

The strangler pattern runs old and new systems in parallel while routing traffic incrementally from old to new, typically from 0% to a canary percentage to full traffic. Once the old system handles zero traffic, it can be removed.

Use compulsory deprecation only when the old system has security issues, blocks progress, or has unsustainable maintenance cost. Advisory deprecation with warnings and documentation is the default when migration is optional and the old system remains stable.

Zombie code is unmaintained code with no owner that still has active consumers, often showing no commits in months and unpatched vulnerable dependencies. It must either be assigned an owner and maintained properly or deprecated with a concrete migration plan.

Users rarely migrate on their own because of Hyrum's Law: they depend on observable behaviors the replacement may not replicate. The team owning the deprecated infrastructure is responsible for providing migration tooling, documentation, or doing the migration itself.