diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b9cd76..940686a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,6 +46,17 @@ already proven: `### Added` / `### Changed` / `### Fixed` headings inside the fragment). Never edit `CHANGELOG.md` for an entry — the release PR assembles the section from the fragments (#112). + + The sole exception is the release PR: it writes no fragment. It consumes + the directory and stamps the section, so a fragment it created would be + absent from + [`changelog-assembled`](https://github.com/heavy-duty/ceremony/blob/a602fd0/actions/changelog-assembled/changelog-assembled.sh)'s + merge-base replay if consumed, or refused by + [`changelog-armed`](https://github.com/heavy-duty/ceremony/blob/a602fd0/actions/changelog-armed/changelog-armed.sh) + if left to survive into the next release. A change that must ship inside + the release PR therefore ships without an entry. If it can wait and wants + an entry, land it as an ordinary PR before the release PR, then rebase and + re-assemble the release. 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/changelog.d/131.md b/changelog.d/131.md new file mode 100644 index 0000000..8b18fcc --- /dev/null +++ b/changelog.d/131.md @@ -0,0 +1 @@ +The changelog rule now explains why release PRs write no fragment and how entry-worthy changes land instead (#131). diff --git a/docs/CONSUMERS.md b/docs/CONSUMERS.md index 5ad6ee8..257417a 100644 --- a/docs/CONSUMERS.md +++ b/docs/CONSUMERS.md @@ -425,6 +425,17 @@ CONTRIBUTING may sharpen it, but this is the floor the guards assume: working the same issue (#112 D2). Never an edit to `CHANGELOG.md`: the release PR assembles the section ([below](#assembling-a-release-section)). + + The sole exception is the release PR: it writes no fragment. It consumes + the directory and stamps the section, so a fragment it created would be + absent from + [`changelog-assembled`](https://github.com/heavy-duty/ceremony/blob/a602fd0/actions/changelog-assembled/changelog-assembled.sh)'s + merge-base replay if consumed, or refused by + [`changelog-armed`](https://github.com/heavy-duty/ceremony/blob/a602fd0/actions/changelog-armed/changelog-armed.sh) + if left to survive into the next release. A change that must ship inside + the release PR therefore ships without an entry. If it can wait and wants + an entry, land it as an ordinary PR before the release PR, then rebase and + re-assemble the release. - **The fragment is the prose, not a description of it** (#112 D3): the exact lines that will be published — no front-matter, no `## ` heading (that one is the assembler's to write). `changelog-armed` refuses a