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 verify 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 to the new column, then drop the old column in a separate later deploy.

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 maintenance cost or security risk justifies forcing migration.

Use the Strangler pattern when replacing a system that serves live traffic. Run old and new systems in parallel, route traffic incrementally from old to new, and remove the old system once it handles zero percent of traffic.

Failures happen when a schema change ships in the same deploy as the code depending on it, so old and new code query incompatible shapes during the rollout window. Ship additive changes first and destructive drops in their own deploy.

Zombie code with active consumers but no maintainer cannot stay in limbo. Either assign an owner who maintains it properly, or deprecate it with a concrete migration plan and removal timeline.