deprecation-and-migration

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, because old and new code run simultaneously during rollout.

First build a production-proven replacement covering all critical use cases, then announce with documentation and migration tooling. Migrate consumers incrementally, verify zero active usage via metrics and logs, and only then remove the old code, tests, and configuration.

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 issues or unsustainable maintenance cost, and it requires providing migration tooling and support.

Use the Strangler pattern when routing traffic incrementally from an old system to a new one until the old handles zero percent. Use an adapter when consumers must keep the old interface while you swap the backend implementation underneath.

Failures happen when a schema change ships in the same deploy as the code depending on it, so one version queries a column that does not exist. The fix is additive phases where old and new code are both valid at every step, plus a tested down migration before merging.

Unused code accumulates security debt, dependency updates, and onboarding overhead that typically exceeds the cost of rebuilding it later. Code that nobody owns but everybody depends on should either get an assigned maintainer or a concrete deprecation plan.