deprecation-and-migration

Announce deprecation with a documented replacement and migration guide, then migrate consumers incrementally one at a time. Use advisory deprecation by default and reserve compulsory deadlines for cases where maintenance cost or security risk justifies forcing migration.

Use the expand/contract pattern: add the new column as nullable, 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. Never rename in place because old and new code run simultaneously during rollouts.

The strangler pattern runs old and new systems in parallel while routing traffic incrementally from old to new, typically moving from 0% to a canary percentage to full cutover. Once the old system handles zero traffic, it can be removed safely.

Default to advisory deprecation with warnings and documentation so users migrate on their own timeline. Use compulsory deprecation with a hard deadline only when the old system has security issues, blocks progress, or has unsustainable maintenance cost, and always provide migration tooling.

Zombie code is unmaintained code with no owner that still has active consumers, often showing no commits in six 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.

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