deprecation-and-migration

Build a production-proven replacement first, announce the deprecation with a migration guide, then migrate consumers incrementally one at a time. Only remove the old system after metrics and logs confirm zero active usage.

Use the expand/contract pattern: add the new column as nullable, dual-write both columns, backfill existing rows in throttled batches, switch reads, 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. Compulsory deprecation requires providing migration tooling, documentation, and support.

Use the strangler pattern when replacing a system incrementally: run old and new in parallel and shift traffic gradually from 0% to 100%. Once the old system handles no traffic, remove it.

Failures happen when a schema change ships in the same deploy as the code using it, so old and new code run simultaneously against incompatible schemas. Additive changes first and destructive changes in a separate deploy prevent this.

Zombie code is unmaintained code with no owner that still has active consumers, often with failing tests or vulnerable dependencies. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan.