forked from heavy-duty/ceremony
docs(builder): a fix round may ride a draft
BUILDER.md's review round assumed ready-throughout, so a builder or reviewer meeting a mid-round draft found behaviour the doctrine never described. Three points, doctrine not mechanism: the draft phase stays the builder's through a fix round, ready-for-review is the builder's own act and no engine's, and where the draft suppressed CI green is proven at the flip with the request following it — step 1's rule at a stated moment, not a second rule. REVIEWER.md gains the reading that keeps a reviewer from misfiling it: a draft carrying state:addressing is a fix round in progress. Refs #258
This commit is contained in:
parent
3c96406081
commit
6634a517bc
3 changed files with 46 additions and 0 deletions
34
BUILDER.md
34
BUILDER.md
|
|
@ -297,6 +297,40 @@ CONTRIBUTING; the shared flow lives here and is not restated there.)
|
|||
is one kind of human-owned decision; use the ruling ask below
|
||||
([#50 D11](https://github.com/heavy-duty/ceremony/issues/50)).
|
||||
|
||||
**A fix round may ride a draft.** An engine may convert a PR back to draft
|
||||
when a round closes, and crew#139's does: the 15-minute cadence makes a
|
||||
builder's fix-round pushes *saves* rather than proposals, and 41 of 106
|
||||
commits across crew's last 25 PRs — 39% — were fired at CI as if they were
|
||||
proposals. Ceremony implements no such conversion and this passage specifies
|
||||
none; it is written down because a builder or a reviewer who meets a mid-round
|
||||
draft has to find a state the doctrine describes. What it means is what a
|
||||
draft already meant during the build, extended and not changed: the draft
|
||||
phase is yours, the panel cannot see it, and the checkpoint discipline
|
||||
(Building, above) runs through the round unaltered. Whose ball it is does not
|
||||
change either — the round outranks the draft flag, which is what
|
||||
[LABELS.md](LABELS.md)'s `state:building` row already says in the machine's
|
||||
voice: a draft carrying a standing non-approving verdict is a fix round and
|
||||
reads `state:addressing` (#205).
|
||||
|
||||
**Ready-for-review is the act that ends the round, and it is the builder's
|
||||
alone.** No engine marks a PR ready. The flip asserts that the round was
|
||||
answered whole, and that assertion is the one judgement about a round its
|
||||
author cannot delegate to a machine: an engine may draft a PR, and crew#139's
|
||||
does, but only the builder undrafts it.
|
||||
|
||||
**Where a draft suppressed the checks, green is proven at the flip and the
|
||||
request still follows it.** Step 1's precondition is the whole rule and this
|
||||
adds no second one — it says only *when* the head answers: marking ready is
|
||||
what runs the checks the draft held back, so the order is flip, let the head
|
||||
answer, then request, and the argued exception stays the only way past a red
|
||||
one. Waiting there is compliance, not a stall, and the machine reads it that
|
||||
way too: `blocker:unrequested` does not fire while a head's checks are pending
|
||||
or red, because the one blocker that demands an act has to know when the act
|
||||
is permitted (#236 — crew#318 carried it at ~12:44Z on 2026-08-03 while its
|
||||
head's run was still in progress, which is the label flagging a builder for
|
||||
obeying this section). A head with no checks configured has nothing to wait
|
||||
for and is requested straight away, the same reading that sweep gives it.
|
||||
|
||||
## The ruling ask
|
||||
|
||||
Set `needs-ruling` whenever a decision belongs to a human: org policy,
|
||||
|
|
|
|||
|
|
@ -141,6 +141,11 @@ saw Y" outranks one that says "this looks like it might".
|
|||
- The builder answers rounds whole and re-requests you; until re-requested,
|
||||
the ball is not yours (`state:addressing` is the builder working — pile-on
|
||||
reviews mid-address just churn the target).
|
||||
- A **draft carrying `state:addressing` is a fix round in progress**, not
|
||||
abandonment: an engine may convert a PR back to draft at round close so the
|
||||
builder's checkpoint pushes stop firing CI, and the flip back to ready is
|
||||
the builder's own act announcing the round is answered
|
||||
([BUILDER.md](BUILDER.md#the-review-round)).
|
||||
- Convergence = every panel verdict approves the current head, no
|
||||
`blocker:*` standing. Then the builder hands off (`state:needs-human`) and
|
||||
the panel's job is done.
|
||||
|
|
|
|||
7
changelog.d/258.md
Normal file
7
changelog.d/258.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
### Added
|
||||
|
||||
- BUILDER.md now describes a fix round that rides a draft: the draft phase
|
||||
stays the builder's, ready-for-review is the builder's own act, and where a
|
||||
draft suppressed the checks green is proven at the flip (#258).
|
||||
- REVIEWER.md now reads a draft carrying `state:addressing` as a fix round in
|
||||
progress rather than abandonment (#258).
|
||||
Loading…
Reference in a new issue