deprecation-and-migration

Deprecate an API by first building a production-proven replacement, then announcing with a migration guide and deadline. Migrate consumers incrementally, verify zero active usage via metrics and logs, and only then remove the old code, tests, and documentation.

Use the expand/contract pattern: add the new nullable column, dual-write both columns, backfill existing rows in throttled batches, switch reads to the new column, then drop the old column in a separate later deploy. Never rename in place.

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 with tooling and support.

Use the Strangler Pattern when replacing a system incrementally: run old and new in parallel and route traffic gradually from 0% to 100%. Once the old system handles zero traffic, remove it safely.

Failures happen when a schema change ships in the same deploy as the code depending on it, so old and new code run simultaneously against incompatible schemas. Decouple them with additive phases and feature flags, and always test the down migration before merging.

Zombie code is unmaintained code with no owner that still has active consumers, accumulating security vulnerabilities and compatibility issues. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan.