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, verify zero active usage via metrics and logs, and only then remove the old code.

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, since old and new code run simultaneously during rollouts.

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 it, and always provide migration tooling and support.

Use the Strangler pattern when routing traffic incrementally from an old system to a new one until the old handles zero percent. Use an adapter when consumers must keep the old interface while the backend implementation is swapped underneath them.

Migrations fail when a schema change ships in the same deploy as the code depending on it, because old and new code run simultaneously and one queries a column that does not exist. Coupling a safe add with a destructive drop, or merging without a tested down path, also causes failures.

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