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

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

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

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 starting with a small canary percentage, and remove the old system once it handles zero traffic.

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

Unused code still incurs maintenance cost through tests, dependency updates, security patches, and onboarding overhead. If functionality is needed later it can be rebuilt, and keeping it typically costs more than rebuilding, so it should be deprecated with a concrete plan.