deprecation-and-migration

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

First build a production-proven replacement, then publish a deprecation notice with a migration guide and tooling. Migrate consumers incrementally, verify zero active usage via metrics and logs, and only then remove the old code, tests, and documentation.

Advisory deprecation uses warnings and documentation so users migrate on their own timeline when the old system is stable. Compulsory deprecation sets a hard removal deadline and is reserved for security risks or unsustainable maintenance cost, and it requires providing migration tooling and support.

Use the Strangler pattern to shift traffic incrementally from an old system to a new one until the old handles zero percent. Use feature flags when you need per-consumer or per-user cutover control and fast rollback between old and new implementations.

A migration without a tested down path cannot be reversed, which means the deploy that applied it cannot be rolled back safely. Write and run the down migration before merging so every phase is independently reversible.

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