From a3e59241b518a49b68c9c5671e4ba38b94cdddb9 Mon Sep 17 00:00:00 2001 From: claude-bot-andresmgsl Date: Fri, 24 Jul 2026 10:22:52 +0000 Subject: [PATCH] docs: builder surfaces write fragments, never CHANGELOG.md CONTRIBUTING's flow item, BUILDER.md's entry rule, and the PR template checklist all point at changelog.d/.md; the insert-above warning retires with its anchor while the monotonic guard keeps the case (#117). --- .github/pull_request_template.md | 4 ++-- BUILDER.md | 12 ++++++++---- CONTRIBUTING.md | 11 ++++++----- README.md | 2 +- 4 files changed, 17 insertions(+), 12 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 763e6fa..81c601b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,8 +11,8 @@ to the issue for triage to amend, not silently unshipped. --> ## Changelog -- [ ] One line under `## Unreleased` — inserted **above** the heading below - it, never over it — or no behavior change, stated here. +- [ ] One fragment, `changelog.d/.md` — the exact prose to publish, + never an edit to `CHANGELOG.md` — or no behavior change, stated here. ## Round log diff --git a/BUILDER.md b/BUILDER.md index 47aa8bf..4ce7949 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -105,10 +105,14 @@ triage bug, and the move is to say so on the issue, not to guess. them as a checklist in the PR body and check them honestly as you go. If one turns out to be wrong or unreachable, say so on the issue and get it amended by triage — do not silently ship less than the issue says. -- Every behavior change adds one line to `CHANGELOG.md` under - `## Unreleased` — in a grouped changelog, append under an existing heading - and create one only when the kind is genuinely new; insert **above** the - heading below, never over it (the monotonic guard's whole reason to exist). +- Every behavior change writes one fragment, `changelog.d/.md`, + named for the authorizing issue (`-.md` when the work is + cross-repo) — the exact prose that will be published, nothing else: `- ` + bullets, and in a grouped repo the `### Added` / `### Changed` / + `### Fixed` headings inside the fragment, creating a rarer kind only when + a change genuinely is one. Never edit `CHANGELOG.md` for an entry — the + release PR assembles the section from the fragments (#112); the monotonic + guard still refuses anything that deletes a shipped heading. - Follow the repo's conventions file and match the code you touch. Tests are not optional: the issue's test plan is the floor, not the ceiling. - **Scope discipline: the PR does the issue — whole, and nothing else.** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1384972..7b9cd76 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,11 +40,12 @@ already proven: 1. **One issue, one PR**, opened as a **draft** while building, with `Closes #N` in the body. Drafts are invisible to the reviewer panel on - purpose. Every behavior change adds one line to `CHANGELOG.md` under - `## Unreleased` (in a grouped changelog, append under an existing heading - and create one only when the kind is genuinely new; insert **above** the - heading below — never type over it; the monotonic guard exists because of - exactly that edit). + purpose. Every behavior change writes one fragment, + `changelog.d/.md` — the exact prose to publish, nothing else + (cross-repo work names it `-.md`; a grouped repo puts its + `### Added` / `### Changed` / `### Fixed` headings inside the fragment). + Never edit `CHANGELOG.md` for an entry — the release PR assembles the + section from the fragments (#112). 2. **When it's ready**: mark ready-for-review and request the whole panel. 3. **Rounds are answered whole.** Wait until every reviewer has a verdict in, then answer the entire round in a **single reply**, push the fixes, and diff --git a/README.md b/README.md index 8fc51c2..65cafdd 100644 --- a/README.md +++ b/README.md @@ -438,6 +438,6 @@ constraints — each bought with an incident, none of them safe to their war stories, in the headers of the scripts they bind: [release.yml](.github/workflows/release.yml#L1-L109), [lib/decide.sh](lib/decide.sh#L1-L74), -[lib/facts.sh](lib/facts.sh#L1-L24), and the three +[lib/facts.sh](lib/facts.sh#L1-L24), and the four [guard scripts](actions/). The comments are the documentation of record; this README is their operator-facing cut.