deprecation-and-migration

Deprecate incrementally: build a production-proven replacement first, publish a migration guide with concrete steps, migrate consumers one at a time, and verify zero active usage via metrics and logs before removing the old code. Default to advisory deprecation unless maintenance cost or risk justifies a hard deadline.

Use the expand/contract pattern instead of renaming in place. Add the new nullable column, 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 once no code references it.

Advisory deprecation uses warnings and documentation so users migrate on their own timeline, while compulsory deprecation sets a hard removal deadline. Compulsory deprecation is reserved for security issues or unsustainable maintenance cost 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 (canary at 10%, then 50%, then 100%), and remove the old system only when it handles zero traffic.

Zombie code is unmaintained code with no owner that still has active consumers, often showing no commits in 6+ months and unpatched vulnerable dependencies. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan — it cannot stay in limbo.

During a rollout, old and new code run simultaneously, so a column renamed or dropped in the same deploy leaves one version querying a column that does not exist. Shipping additive changes first and destructive changes last keeps both code versions valid at every step.