deprecate-and-migrate

Deprecate and migrate

Contract

Inputs

• The deprecated system: its VCS-tracked code, tests, config, and docs, and the full set of consumers. Must be supplied.
• A replacement that is production-proven and covers every critical use case of the old system, or a decision to build one first. Must exist before any removal.
• Current usage evidence: metrics, logs, and dependency analysis proving active usage. Must be supplied to prove zero usage before removal.
• Optional: a hard removal deadline (compulsory deprecation) and migration tooling.

Procedure

1. Bound scope. List the deprecated system's VCS-tracked files (code, tests, config, docs) and every consumer. Show this exact set before any mutation; do not mutate untracked targets. Done when: the tracked file and consumer set is shown before mutation.
2. Make the maintain-or-sunset decision. Answer, in order: does the system still provide unique value (if yes, maintain it and stop); how many consumers depend on it; does a production-proven replacement exist (if no, build it first); what is each consumer's migration cost; what is the ongoing maintenance cost of not deprecating. Stop at maintain if the system still provides unique value. Done when: maintain or sunset is chosen from the recorded evidence.
3. Choose the deprecation pressure. Default to advisory: warnings, documentation, and nudges, with users migrating on their own timeline. Use compulsory (a hard removal deadline plus shipped migration tooling, documentation, and support) only when maintenance cost or security risk forces it. A deadline alone is not a migration. Done when: advisory or compulsory pressure is chosen with its condition stated.
4. Verify the replacement is production-proven and covers every critical use case of the old system, with a migration guide containing concrete steps and examples. No deprecation proceeds without a working, production-proven alternative. Done when: every critical use case has production evidence and migration guidance.
5. Announce. Write a deprecation notice naming status, replacement, removal date, and reason, plus the migration guide. Done when: the notice and guide contain all named fields.
6. Migrate consumers one at a time. For each consumer: identify all touchpoints with the old system, update to the replacement, verify behavior matches via tests and integration checks, remove old-system references, and confirm no regressions. For a formal cutover, sequence consumers under one approved rollback boundary; never leave the old and new paths active together after the cutover. The Churn Rule: the owner of deprecated infrastructure owns migrating every consumer in the same cutover; do not shift migration work to consumers or carry a compatibility path. Done when: every consumer uses only the replacement and passes its checks.
7. Prove zero active usage via metrics, logs, and dependency analysis. Done when: all three evidence sources show zero usage.
8. Remove the old system. Delete the code, associated tests, documentation, configuration, and the deprecation notices. Commit each removal so version control is the recovery path. Done when: obsolete tracked artifacts are removed in recoverable commits.
9. Record rollback and monitoring evidence: the commit range that reverts the removal, and the metric/log watch set that confirms no consumer regressed after removal. Done when: the revert range and watch set are recorded.