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 a column in place.

First build a production-proven replacement, then announce the deprecation with a migration guide and tooling, migrate consumers incrementally, and verify zero active usage via metrics and logs before removing the old code, tests, and documentation.

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 the backend implementation is swapped underneath.

Failures happen when a schema change ships in the same deploy as the code depending on it, because old and new code run simultaneously and one queries a column that does not exist. Additive phases keep both code versions valid at every step.

Unused code still incurs maintenance cost through security patches, dependency updates, and onboarding overhead. If functionality is needed later it can be rebuilt, and zombie code with no owner must either receive investment or a concrete removal plan.