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

First build a production-proven replacement, then announce deprecation with a migration guide and tooling. Migrate consumers incrementally using the strangler pattern or feature flags, verify zero active usage via metrics and logs, and only then remove 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.

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

Do not deprecate when the system still provides unique value, when no working replacement exists, or when migration cost clearly exceeds the ongoing maintenance cost. Also avoid deprecating without measuring current usage, since hidden consumers may depend on undocumented behavior.