deprecation-and-migration

Deprecate a legacy API by first building a production-proven replacement, then announcing with documentation and migration tooling. Migrate consumers incrementally using patterns like the Strangler approach or feature flags, and verify zero active usage via metrics before removing the old code.

Rename a column using expand/contract: add the new nullable column, 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, since old and new code run simultaneously during rollout.

Advisory deprecation uses warnings and documentation so users migrate on their own timeline, while compulsory deprecation sets a hard removal deadline. Default to advisory; use compulsory only when security risk or maintenance cost justifies forcing migration, and always provide migration tooling.

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 (0%, 10%, 50%, 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 vulnerabilities. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan; it cannot stay in limbo.

A migration without a tested down path is a deploy you cannot roll back if something fails. Write and run the rollback before merging, and keep destructive steps like drops in their own deploy after no code references the old schema shape.