deprecation-and-migration

Deprecate an API by first building a production-proven replacement, then announcing with documentation and migration tooling. Migrate consumers incrementally, verify zero active usage through metrics and logs, and only then remove the old system.

Rename a column using expand/contract: add the new column as nullable, 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.

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.

Use the Strangler pattern when replacing a system that handles 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 are coupled to code changes: during rollout, old and new code run simultaneously and one queries a column that doesn't exist. Fix this with additive phases so both code versions are valid at every step.

Zombie code with active consumers but no maintainer must either get an assigned owner with proper maintenance or be deprecated with a concrete migration plan. Leaving it in limbo accumulates security vulnerabilities and compatibility issues.