deprecation-and-migration

Build a production-proven replacement first, then announce deprecation with a migration guide and tooling. Migrate consumers incrementally one at a time, verify zero active usage through metrics and logs, and only then remove the old system.

Use the expand/contract pattern: add the new column as nullable, 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 when the old system is stable. Compulsory deprecation sets a hard removal deadline and is reserved for security risks or unsustainable maintenance costs, and it requires providing migration tooling and support.

Use the Strangler pattern when replacing a system that handles live traffic. Run old and new systems in parallel, route traffic incrementally from old to new starting with a small canary percentage, and remove the old system once it handles zero traffic.

Zombie code is unmaintained code with no owner that still has active consumers, often showing no commits in six months or unpatched vulnerable dependencies. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan.

A migration without a tested down path cannot be reversed, making the associated deploy impossible to roll back safely. Write and run the down migration before merging so every schema change is recoverable.