diff --git a/BUILDER.md b/BUILDER.md index a2f6671..13a395d 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -208,9 +208,9 @@ triage bug, and the move is to say so on the issue, not to guess. ## The review round -(If you are reading this as `.ceremony/BUILDER.md` in a governed repo: the -panel roster and any repo-specific flow notes live in that repo's own -CONTRIBUTING; everything below is the shared flow.) +(If you are reading this as `.ceremony/BUILDER.md` in a governed repo: +repo-specific facts such as the panel roster live in that repo's own +CONTRIBUTING; the shared flow lives here and is not restated there.) 1. Mark ready-for-review; request **the whole panel**. The panel is the roster of the repo the **PR** is in, minus you — never the roster of the repo the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 31931e2..7b1666c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,45 +35,9 @@ Who may set which label is [LABELS.md](LABELS.md)'s contract. ## The PR flow -The same flow the sibling repos run, and the part of this pipeline that is -already proven: - -1. **One issue, one PR**, opened as a **draft** while building, with - `Closes #N` in the body — its exceptions (cross-repo work, a post-merge - criterion) live in [BUILDER.md](BUILDER.md). Drafts are invisible to the - reviewer panel on 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). - - 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 - re-request the reviewers that didn't approve. Prefer verification over - argument: a test settles what a comment thread can't. -4. **Reviews end in a verdict** — approve or request-changes, never a bare - comment. The verdict carries blockingness only; the body carries the - feedback. ([REVIEWER.md](REVIEWER.md) for why a comment-only review stalls - the machine.) -5. **Handoff**: when the round passes — every panel verdict is an approval of - the current head and no `blocker:*` label stands — the engine requests the - human's review, sets `state:needs-human`, and posts the handoff facts - (approvals at the current head, head SHA, and Round-log pointer) on the - author's behalf. The label write is optimistic; the reconciler validates - it within seconds. -6. **A human merges.** Nothing else merges. +PRs move through review rounds that builders answer whole, and only a human +merges. [BUILDER.md](BUILDER.md) is the shared flow contract; this file names +only ceremony-specific facts such as the roster and code conventions. ### Roster diff --git a/changelog.d/198.md b/changelog.d/198.md new file mode 100644 index 0000000..0e3326f --- /dev/null +++ b/changelog.d/198.md @@ -0,0 +1,5 @@ +### Changed + +- `CONTRIBUTING.md` now points to `BUILDER.md` for the shared PR flow instead + of restating doctrine that can drift, while retaining ceremony's roster and + other repo-specific facts (#198).