mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-04 10:24:02 +00:00
Said TurkseverandClaude Opus 5.5
4d42516ffe
`--write` wrote CHANGELOG.md and then removed fragments one by one, so a failure after the write left surviving fragments that a rerun spliced in a second time. The write is now staged. The assembled file goes into changelog.d/.assembling/, the fragments are renamed in beside it, and renaming the assembled file over CHANGELOG.md is the single commit point. A run that fails rolls itself back when it can; otherwise the next `npm run changelog` reads the staging directory and either restores the fragments (assembled file still staged) or deletes the leftovers (batch landed). `--check` reports a staged batch instead of reporting past it. A failure-injection test makes every filesystem call in a `--write` fail in turn, both as a one-off error and as a crash with no in-process rollback. It asserts the retry produces exactly the uninterrupted CHANGELOG.md, with each entry once and an empty directory. The test fails against the previous write-then-delete and against delete-first. Co-Authored-By: Claude Opus 5.5 <[email protected]>
53 lines
2.3 KiB
Markdown
53 lines
2.3 KiB
Markdown
# Changelog fragments
|
|
|
|
One file per entry. A pull request adds a file here instead of editing
|
|
`CHANGELOG.md`, and a release concatenates them into it.
|
|
|
|
```
|
|
changelog.d/<pull request number>-<slug>.md
|
|
```
|
|
|
|
`723-atc-decision-layer.md`, for example. The slug is lowercase, words separated
|
|
by `-`. Two pull requests never pick the same filename, because the pull request
|
|
number is already unique — which is the point: new `CHANGELOG.md` entries go at
|
|
the top of the file, so two pull requests in flight write into the same few lines
|
|
and git has nothing to merge on.
|
|
|
|
Write the file exactly as the entry should read in `CHANGELOG.md`: a `-` bullet,
|
|
wrapped the way the surrounding entries are, crediting yourself and the pull
|
|
request.
|
|
|
|
```markdown
|
|
- Report which upstream declined a Street Traffic road load. The layer row now
|
|
reads `Overpass rate-limited` instead of a general "Road data temporarily
|
|
unavailable" (yourname, #665).
|
|
```
|
|
|
|
The text is spliced in unchanged apart from trailing whitespace, so what you
|
|
write here is what ships. Fragments are deliberately outside
|
|
`scripts/format-scope.json`, so `npm run format` never reflows one.
|
|
|
|
At release time:
|
|
|
|
```
|
|
npm run changelog:check # list what would move, change nothing
|
|
npm run changelog # move every fragment into CHANGELOG.md
|
|
```
|
|
|
|
The assembler refuses a batch rather than guessing: a filename that is not
|
|
`<pull request>-<slug>.md`, or two fragments claiming one pull request number,
|
|
stops the run before anything is written and names the files.
|
|
|
|
If `npm run changelog` fails part-way (a full disk, a killed process), run it
|
|
again. The batch is staged in `changelog.d/.assembling/` and only lands when the
|
|
assembled file replaces `CHANGELOG.md` in a single rename, so the rerun either
|
|
finishes that batch or puts its fragments back first. It never adds an entry
|
|
twice or drops one. `npm run changelog:check` names a staged batch, if one is
|
|
left over, instead of reporting past it.
|
|
|
|
A documentation claim that needs a regression test — the way
|
|
`src/annotations/drawTool.test.mjs` asserts against `CHANGELOG.md` — should
|
|
assert against `docs/CURRENT-STATE.md` or `README.md` instead. A pull request
|
|
still edits those directly, so the text is in the file while the change is under
|
|
review; a fragment does not reach `CHANGELOG.md` until release.
|