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

First build a production-proven replacement covering all critical use cases, then publish a deprecation notice with a migration guide and tooling. Migrate consumers incrementally, verify zero active usage with 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.

During a rolling deploy, old and new code run at the same time, so one version queries a column that no longer exists. The fix is to never change a column in place: ship additive changes first and destructive drops in their own deploy after no code references the old shape.

Use the Strangler pattern when you can route traffic incrementally between old and new systems until the old one handles zero percent. Use an adapter when consumers must keep the old interface while you swap the backend implementation underneath.

Zombie code cannot stay in limbo: either assign an owner who maintains it properly, or deprecate it with a concrete migration plan. Signs include no commits in six months with active consumers, unfixed failing tests, and unpatched vulnerable dependencies.