# Migration guides

One file per major-version transition: `v<X>-to-v<Y>.md` (e.g. `v2-to-v3.md`). Created only when at least one breaking change requires more than a one-line migration; trivial migrations stay inline in `CHANGELOG.md`.

## File structure

Each migration file is organized by **affected subpath export**, then by symbol:

```markdown
# vX → vY migration

## @yaoc1996/js-tools/<subpath>

### <symbol>

**What changed:** <one-line summary>

**Before:**
\`\`\`ts
// old call site
\`\`\`

**After:**
\`\`\`ts
// new call site
\`\`\`

**Find call sites:**
\`\`\`
rg "\\b<symbol>\\b" --type ts --type tsx
\`\`\`
```

Always include the grep pattern — that's what makes the guide actionable for a downstream agent.

## When to write one

From `.claude/contexts/breaking-changes.md`:

- Removed or renamed export → inline note in `CHANGELOG.md` is usually enough.
- Signature change with non-obvious adapter logic → migration file.
- Behavioral change with no type-level signal → migration file (this is the most important case — types won't catch it).
- Cross-module rearrangement → migration file.
