75 lines
2.7 KiB
Markdown
75 lines
2.7 KiB
Markdown
|
# Cut map shape
|
||
|
|
|
||
|
|
A migration keeps two documents in the repo it changes.
|
||
|
|
|
||
|
|
- **Target** (`docs/<migration>-target.md`): the ends. It holds the invariants,
|
||
|
|
the canonical implementations, what is not a consumer, and the durable design
|
||
|
|
truths the migration produces. When the migration closes, the target is
|
||
|
|
reconciled with the Body and outlives the map.
|
||
|
|
- **Cut map** (`docs/<migration>-cut.md`): the means. It is a status header
|
||
|
|
followed by one section per cut. It is history once the migration closes.
|
||
|
|
|
||
|
|
## Status header
|
||
|
|
|
||
|
|
The header owns progress. Self updates it in every landing commit.
|
||
|
|
|
||
|
|
```
|
||
|
|
Status: cut map. Ends are owned by <target>; this document owns the means.
|
||
|
|
|
||
|
|
<for each landed cut>
|
||
|
|
Cut N landed at <repo> <sha range>. Verified: <builds/tests/captures>. Soul
|
||
|
|
found <defects>, all fixed | recorded. Recorded, not fixed: <items, why>.
|
||
|
|
|
||
|
|
Rulings (operator, <date>):
|
||
|
|
- **QN-M <choice>:** <ruling>. <quote if the wording carries meaning>.
|
||
|
|
(Supersedes <earlier ruling>; the old text below is history.)
|
||
|
|
|
||
|
|
Open: <operator checks, pending Soul passes, questions>.
|
||
|
|
Follow-ups outside this migration: <item, file, reason it can wait>.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Per-cut section
|
||
|
|
|
||
|
|
```
|
||
|
|
### Cut N. <name>
|
||
|
|
|
||
|
|
- **Repo/branch:** <repo> <branch> from <base>. Depends on <cuts, releases>.
|
||
|
|
- **First:** <captures or pins taken before any edit>.
|
||
|
|
- **Deletes first:** <path (lines)>, ...
|
||
|
|
- **Keeps and moves:** ...
|
||
|
|
- **Adds:** ...
|
||
|
|
- **Per-file changes:** <file:line against HEAD sha>: <change>.
|
||
|
|
- **Authority map:**
|
||
|
|
- Owner:
|
||
|
|
- Inputs:
|
||
|
|
- Outputs:
|
||
|
|
- Derived state:
|
||
|
|
- Forbidden writers:
|
||
|
|
- Shared paths:
|
||
|
|
- Deletion line:
|
||
|
|
- **Verification:**
|
||
|
|
- builds: <exact projects>
|
||
|
|
- tests: <name> pins <rule>
|
||
|
|
- negative: <rg pattern, verified to not collide with legitimate names>
|
||
|
|
- operator: <play smoke steps; Studio click-through>
|
||
|
|
- **Operator questions:** QN-1 <question>. A: ... B: ... **Recommended: A**, because ...
|
||
|
|
```
|
||
|
|
|
||
|
|
## Subtraction ledger
|
||
|
|
|
||
|
|
One row per cut: the lines removed, the lines added, and the dependencies,
|
||
|
|
formats and targets removed or added. Compare the estimate with what landed in
|
||
|
|
the postmortem.
|
||
|
|
|
||
|
|
## Notes from use
|
||
|
|
|
||
|
|
- **Test negative greps before publishing them.** `\.loadout\b` matched the
|
||
|
|
legitimate schema name `aetheria.loadout`.
|
||
|
|
- **State the capture method with the capture.** PowerShell `>` writes a BOM and
|
||
|
|
CRLF, and the comparison must use the same method on both sides.
|
||
|
|
- **Prefer normalizers that parse the format.** Ones that split on text leave
|
||
|
|
false diffs, as the census normalizer did when it split on `, ` and glued the
|
||
|
|
first maker to its kind column.
|
||
|
|
- **When a later ruling changes a design, sweep the whole map.** Rewrite the header
|
||
|
|
and routing tables, and mark the older spec text as history, so no one reads two
|
||
|
|
live designs.
|