addy-deprecation-and-migration

Deprecate safely by first building a production-proven replacement, then announcing with documentation and migration guides, migrating consumers incrementally, and removing the old system only after verifying zero active usage through metrics and logs.

Use the expand/contract pattern: 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.

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

Use the Strangler pattern when replacing a system serving live traffic. Run old and new systems in parallel, route traffic incrementally from old to new, and remove the old system once it handles zero percent of traffic.

Migrations fail when schema changes couple to code changes, because old and new code run simultaneously during rollout and one queries a column that does not exist. Never change columns in place; migrate in additive phases with tested down paths.

Zombie code is unmaintained code with active consumers, no owner, and accumulating vulnerabilities. Teams must either assign an owner and maintain it properly or deprecate it with a concrete migration plan, since limbo is not acceptable.