From 52dfc5c5c1da73577581fcb0cf5b30fc90dca266 Mon Sep 17 00:00:00 2001 From: dan-claude-bot Date: Sat, 18 Jul 2026 18:50:51 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20reviews=20end=20in=20a=20verdict=20?= =?UTF-8?q?=E2=80=94=20approve=20or=20request=20changes,=20never=20a=20bar?= =?UTF-8?q?e=20comment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Maintainer rule: a comment-only review is a non-verdict the state machine (and the board) cannot read. Verdict carries blockingness only; nits ride an approval, blockers — including verdict-gating questions — are request-changes. Co-Authored-By: Claude Fable 5 --- CONTRIBUTING.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f32e3d..020ac23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,9 +17,19 @@ labels tell you where everything is without opening anything. answer the entire round in a **single reply**, push the fixes, and re-request the bots that didn't approve. Prefer verification over argument: a test settles what a comment thread can't. -5. **When all three approve**, the final review goes to the maintainer — the +5. **Reviews end in a verdict.** A reviewer — bot or human — either + **approves** or **requests changes**, never a bare comment. A + comment-only review is a non-verdict: it doesn't say whether the round + passed, and the state machine (and anyone scanning the board) has to + guess. The verdict carries *blockingness only*, the body carries the + feedback: non-blocking nits ride an **approval** and the author addresses + them at their discretion; anything blocking — including a question that + gates the verdict — is **request changes**, saying what unblocks it. The + reconciler treats a comment-only review as not-approved, so commenting + without a verdict only stalls the PR. +6. **When all three approve**, the final review goes to the maintainer — the labels workflow requests it automatically. -6. **Checks must be green**: `shellcheck` and `bash test/cli.sh` locally +7. **Checks must be green**: `shellcheck` and `bash test/cli.sh` locally mirror what CI runs; the db dump/restore round-trip (`test/db-integration.sh`) executes in CI where Docker is present.