Documentation
README
migration-guide โ write upgrade steps for a breaking change
Produce a guide that lets a user on the old version land on the new one with the least friction.
Pin down what actually broke
Identify the precise breaking change before writing a word. Get it from the diff and history, not from the description alone:
git diff <old>..<new>on the affected surface, andgh pr view <n>for the PR that introduced it.- Dispatch the researcher (
purpose: explore) to confirm the exact old and new shapes: the old name/signature/default, the new one, and whether a compatibility shim or deprecation window exists.
Never document a rename or signature change from memory โ the exact symbols are what users will copy.
Structure
# Migrating to <version>
This is the opening of the README. Read the full README on GitHub.