version-migration-guide

Inventory every breaking change from the tag-to-tag API diff rather than the changelog, order entries by blast radius, and give each change a detection signal, before/after code, a fix, and an escape hatch. Verify the guide by running a cold upgrade of a real project using only the document.

A changelog records what shipped in a release; a migration guide tells the reader what they must now do, in the order they must do it. Any sentence that does not change what the reader types is overhead and belongs in the changelog or a blog post.

Build a codemod when the blast radius crosses hundreds of call sites per consumer or consumers cannot hold a long-lived migration branch. Otherwise ship search patterns and literal error messages first, since they cost near-zero and serve both humans and coding agents.

No. Under the Churn Rule from Software Engineering at Google, when you control all consumers you should perform the migration yourself with a codemod plus a short note. A guide is the right deliverable only when consumers are genuinely other people's codebases.

A hosted API guide must add per-request version pinning with a full example request, a surface matrix across SDKs and webhooks, a data-layer impact section, and an ordered cutover-and-rollback procedure. Webhooks need their own section because consumers cannot pin inbound requests.

Run a cold upgrade: have someone who did not write the guide upgrade a real project using only the document. Publish the measured elapsed time as the effort estimate, check completeness against the API diff, and confirm the codemod's residue is named.