deprecation-and-migration

Use the expand/contract pattern: add the new column as nullable, dual-write both columns from the app, 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.

First build a production-proven replacement, then announce with a migration guide and tooling, migrate consumers incrementally, and verify zero usage via metrics and logs before removing the old code. Default to advisory deprecation unless maintenance cost or risk justifies a hard deadline.

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 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 old and new code run simultaneously against incompatible shapes. Decouple them with additive phases, feature flags, and a tested down path for every migration.

Maintaining two systems doubles testing, documentation, and onboarding cost, while unmaintained zombie code accumulates security vulnerabilities. Either assign an owner and invest in the system, or deprecate it with a concrete migration plan.