# `docs/cutover/` — per-release breaking-change guides

**Per `DOC-05`:** one guide per release that breaks a documented
surface (MAJOR — or MINOR within `0.x` per `AP-03`). The guide is
the **consumer's runway** between two pinned versions: read it
once when bumping, know exactly what to do.

## What goes here

- **One file per breaking release**, named `v<X.Y.Z>.md` after
  the version that *contains* the breakage (the TO version,
  not the FROM).
- The four mandatory sections (per `DOC-05`):
  1. **What was removed / renamed / reshaped** — table of
     literal old name → literal new name + codemod yes/no.
  2. **Quickest path — `mgf-fed migrate`** — the codemod
     recipe with `--dry-run` preview.
  3. **Manual: each non-codemoddable change** — copy-pasteable
     before/after blocks.
  4. **Closes FEEDBACK `<ID>`** — back-link to the design
     record (where applicable).

## What does NOT go here

- **The CHANGELOG entry** → root `CHANGELOG.md` per `DOC-04`.
  The cutover guide is the *consumer-facing migration recipe*;
  the CHANGELOG is the *engineering audit trail*. Both
  cross-reference the other.
- **Internal-posture audits of the change** → the relevant
  `docs/inprogress/<tracker>.md` (RA / SH / PC).
- **Design rationale for WHY the change happened** →
  `docs/design/` or the FEEDBACK entry.

## Naming + numbering

| Convention | Rule |
|---|---|
| **File name (single-package)** | `v<X.Y.Z>.md` (exact tag, no prefix) |
| **File name (federation aggregate)** | `federation-v<X.Y>.md` (mgf-common's MINOR, not the PATCH) — covers a multi-sibling pin walk in one read. See [`federation-v0.34.0.md`](federation-v0.34.0.md) for the canonical example + the template inside §3. Use when 2+ siblings need a pin walk in the same mgf-common cycle. |
| **First-version-with-the-break** | The TO version, not the FROM (consumer pins to TO and reads THIS file) |
| **Empty cutover** | Skip the file entirely if the release contains no breaking surface change. A no-op MINOR doesn't need a v file. |
| **Archive** | Cutover guides stay here permanently — they're the migration record. NOT moved to `docs/archive/` (per `DOC-11`, the archive cadence applies to trackers, not migration docs). |

## Index

Every release that touched the public surface from `v0.22.0`
onward has its own file. The pre-v0.22 history lives in the
`archive/` subdirectory (early-development reshape; not
consumer-facing). The current files:

```bash
ls docs/cutover/v*.md   # 12 files: v0.22.0 → v0.33.0
```

For the most recent breaking change, see the highest-numbered
file. For a migration spanning multiple versions, read in order:
each file assumes the consumer is coming from the immediately-
preceding version.
