How to write and maintain migration docs. One file per behavior change lives under docs/migration/; the reader-facing overview is MIGRATION.md. This page is the single source of truth for naming, workflow, and entry structure — do not append long entries to MIGRATION.md.
docs/migration/issue-<issue-number-zero-padded>-<short-slug>.md
Examples: issue-0002-config-files.md, issue-0569-cli-round.md.
Zero-pad the issue number to four digits so filenames sort in issue order.
| Do | Don't |
|---|---|
Add one new issue-NNNN-*.md per PR |
Append sections to MIGRATION.md |
| Edit only your issue’s file when updating wording | Edit another issue’s migration file |
| On release, set Minimum version in that file | Rename files unless the issue number was wrong |
Parallel PRs touch different paths → Git merges cleanly.
Every file in docs/migration/ must use these headings in order (omit only when a section truly does not apply):
| Section | Required? | Content |
|---|---|---|
| Minimum version | Yes | Semver when shipped; pending before release |
| What changed | Yes | One short summary |
| Before | Yes | Behavior on older releases |
| After | Yes | Behavior on the fixed release |
| Workaround on older versions | Yes when applicable | Concrete steps users on an older npm version can take without upgrading (config shape, CLI flags, external tools, pinned version). Do not skip for bug fixes — if the bug is CLI-only, document a config/API path that still works. |
| After upgrading | Yes | npm install webfont@… and the new recommended command or config |
When no practical workaround exists (rare), keep the heading and write None with one sentence explaining why (for example the old release cannot perform the operation at all).
Example workaround patterns
- Bug on CLI flag → use cosmiconfig with a typed value (number in JSON/JS config instead of a string from argv).
- Missing feature → external tool or script until upgrade.
- Config vs CLI conflict → pass input only on the command line on older releases.
On release: edit only that issue’s file — set Minimum version and trim workarounds that only applied to pre-release builds.
- GitHub: search
issue-0569indocs/migration/ - Local:
ls docs/migration/issue-*.md
Link the file from the GitHub issue and PR (Related issue / comments).