314aa77ee8
Prompted by hyperhive/hyperhive#3050: a reviewer held a formal approve/request-changes verdict for CI to go green, which delayed a merge that was only waiting on the review. CI, review approval, and auto-merge arming are three independent gate conditions — a reviewer is only responsible for the second one. Documents the asymmetry that follows from auto-merge sometimes being armed before a review lands: an unnecessary request-changes costs a round-trip, but an approve given on lingering doubt can ship immediately with no further human check. Default to holding when unsure.
3.9 KiB
The PR review gate
What a review verdict means in this hive, why a reviewer shouldn't wait on CI to submit one, and what an operator setting up a fresh hive should know before arming auto-merge. Prompted by a live mistake: a reviewer held a formal approve/request-changes verdict back "until CI is green," which is not the reviewer's job to gate on and just delayed a merge that was already waiting on the review alone (hyperhive/hyperhive#3050).
The gate has three independent parts
A PR merges when all of:
- CI is green — the repo's required status checks pass on the PR's current head commit.
- Every requested review is
APPROVED, and none is stale — Forgejo marks a review stale the moment a new commit lands on the branch after it; a stale approve does not count. - Someone with write access has armed the PR to merge — either a manual merge once 1 and 2 hold, or Forgejo's auto-merge (merge the instant the other two conditions are met, no human back in the loop at that moment).
These three are independent. A reviewer is only ever responsible for part 2. Waiting on part 1 before submitting a verdict doesn't make the review "more correct" — it just delays the gate for no reason, since CI resolves on its own regardless of what the review says.
Reviewers: submit the verdict, don't gate on CI
Submit hive-forge pr-reviews <pr> --approve or --request-changes
as soon as you've finished checking the diff — not once CI
happens to be green. Mention CI's current state in the review body if
it's relevant (e.g. "approving; nix flake check is still running"),
but don't hold the formal verdict hostage to it. CI is not a signal a
reviewer waits on; it's a parallel, independent gate that resolves on
its own.
This matters concretely because of how auto-merge interacts with review timing:
An operator may arm auto-merge before your review lands. If they
have, and CI is already green, your APPROVED review is the
trigger — the merge happens the instant Forgejo records your
review, with no further human check. There is no "let me look this
over once more before it actually merges" step once you've approved.
The practical consequence: lean hard toward request-changes when
in doubt, including for things that feel minor — a comment that's
slightly wrong, a claim you haven't fully verified, a doc that might
be stale. On a repo without auto-merge armed, an unnecessary
request-changes costs a re-review round-trip. On one where
auto-merge is armed, an approve you weren't fully sure of ships
immediately. That asymmetry is why the default under uncertainty is
to hold, not wave through.
Corollary: don't read "submit promptly" as "submit hastily." The fix isn't rushing the check, it's not padding the check with an extra, unrelated wait (CI) that was never yours to hold.
Re-review after every push
A stale review (Forgejo flags it in the PR's review list once a new commit lands) does not count toward the gate. If a PR you've reviewed gets a follow-up commit — even a "just a wording fix" or "just trimming comments" commit — re-diff it and submit a fresh verdict before it can merge. Don't assume a small-sounding commit message accurately describes the diff; verify it the same way you verified the original.
Operators: what arming auto-merge actually commits you to
Setting a PR to auto-merge in Forgejo means: the moment CI is green
and every requested review is an approve, the PR merges — with no
further chance for a human to look at it. If you arm it before a
review has landed, you are trusting that reviewer's eventual
APPROVED completely; there's no second gate after them.
If that's not what you want for a given PR (e.g. you want to glance at it yourself even after the requested reviewer approves), don't arm auto-merge — merge manually once the gate conditions are met, or add yourself as a required reviewer too so the gate's part 2 doesn't close on the requested reviewer's approve alone.