deprecation-and-migration

Deprecate an API by first shipping a production-proven replacement, then announcing with a migration guide and tooling. Migrate consumers incrementally using the Strangler Pattern or feature flags, and only remove the old system after metrics confirm zero active usage.

Rename a column using expand/contract: 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. 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, and always provide 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 through canary phases, and remove the old system once it handles zero percent of traffic.

Migrations fail when a schema change ships in the same deploy as the code depending on it, because old and new code run simultaneously during rollout and one queries a column that does not exist. Ship additive changes first and destructive changes in a separate deploy.

Zombie code with no owner but active consumers cannot stay in limbo. Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan, since unmaintained code accumulates security vulnerabilities and compatibility issues.