deprecation-and-migration

Deprecate safely by first building a production-proven replacement, then announcing with documentation and a migration guide. Migrate consumers incrementally one at a time, verify zero active usage through metrics and logs, and only then remove the old code, tests, and configuration.

The strangler pattern runs old and new systems in parallel while routing traffic incrementally from old to new. Start with a small canary percentage, scale to full traffic on the new system, and remove the old system once it handles zero percent of requests.

Default to advisory deprecation with warnings and documentation when migration is optional and the old system is stable. Use compulsory deprecation with a hard deadline only when security issues, blocked progress, or unsustainable maintenance costs justify forcing migration, and always provide migration tooling.

Use the adapter pattern to translate old interface calls to the new implementation, letting consumers keep existing code while the backend changes. Feature flags let you switch individual consumers from old to new systems one at a time with controlled rollback.

Zombie code is unmaintained code with no owner that still has active consumers, often showing no commits in months, failing tests, and unpatched vulnerabilities. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan; it cannot stay in limbo.