mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-19 06:34:43 +01:00
A round grant at the review round cap buys the fix round it names (GST-2968) (#4479)
When /ship stops at a pull request's review round cap, a grant naming that stop now buys one scoped review of the fix, in the same run or the next, instead of another read-only full review. Before, a grant recorded after the read-only review, or between /ship runs, bought nothing, so teams paid for extra full reviews or second grants (ghome#40: $8.78 against about $3). Nothing to do: /ship prints the grant command when it stops. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> Review-Finding: p1/specialist-batched#1 reader=security Review-Finding: p1/specialist-batched#2 reader=state-machines Review-Finding: p1/specialist-batched#3 reader=testing Review-Finding: p1/red-team#1 reader=red-team Review-Finding: p1/red-team#2 reader=red-team Review-Finding: p1/red-team#3 reader=red-team
This commit is contained in:
1 parent
33b1a965ba
commit
f87d4325a3
28 files changed
+761
-86
No files matched your search
+44
-15
@@ -187,26 +187,55 @@ caught on another crew's PRs.
|
||||
full passes only, by design (`lib/review-depth.ts` `prCapped`): earlier runs'
|
||||
fix-checks and scoped passes show in `pr_rounds=` but don't count against it,
|
||||
because each run's own fix round is the in-run table's call. A full pass past two
|
||||
stops with `PR_ROUND_CAP` and prints the exact `gstack-approvals
|
||||
round-grant` command; a below-floor fix at the cap finishes with its notes
|
||||
listed. The stop is the lane's or Captain's call, never an owner ask
|
||||
stops with `PR_ROUND_CAP` and says how to record the stop and its grant
|
||||
(item 6); a below-floor fix at the cap finishes with its notes listed. The stop is the lane's or Captain's call, never an owner ask
|
||||
([troubleshooting](troubleshooting.md#pr-round-cap)).
|
||||
5. **Read-only final review.** A PR that already had two full rounds and whose
|
||||
own code changed since still gets one full review of its final head. It has
|
||||
no fix round: below-floor findings ship as notes, and a blocker (open or
|
||||
fixed) or a gate-class edit stops with `PR_ROUND_CAP` for the lane's Captain
|
||||
to decide: ship with the note, or park. A round grant recorded after the
|
||||
read-only review doesn't buy a fix round, because that review already spent
|
||||
the round the grant would add. The count does not reopen.
|
||||
6. **Round grant.** `gstack-approvals round-grant --pr <n> --head <sha> --kind
|
||||
extra-round --reason <why> --by <lane or Captain>` records one grant for one
|
||||
head: one round past the cap, with its fix round, instead of the read-only
|
||||
review. Step 1's `PR_REVIEW_FLAGS:` then adds `--round-grant <id>`, which
|
||||
raises that run's cap by one round, and the plan refuses a grant for another
|
||||
head or PR. The plan keeps the grant after the fix round's commits move HEAD
|
||||
past it. gstack never grants itself a round: `--by gstack` and a grant
|
||||
from inside an open `/ship` run are refused, and `add` refuses the scope.
|
||||
The receipt lists grants under `review_round_grants`.
|
||||
to decide: ship with the note, park, or buy that review's fix round with a
|
||||
fix-check grant (item 6). The count does not reopen.
|
||||
6. **Round grants.** Two kinds, each recorded with `gstack-approvals round-grant
|
||||
--pr <n> --head <sha> --reason <why> --by <lane or Captain>`, and each spent
|
||||
by the one run that claims it.
|
||||
- **`--kind fix-check`, after a stop** (GST-2968). When a review stops,
|
||||
`/ship` runs `gstack-ship-receipt stop`, which writes a stop record into
|
||||
the PR body's runs block: the run, and the commit and tree the stopped review
|
||||
read. It writes one only when that review finished, read one committed tree
|
||||
from start to end on a clean checkout, and that commit is HEAD or under it
|
||||
(`STOP_UNBOUND` otherwise). The grant names that stop's head, its run
|
||||
(`--stop-run`) and the findings its fix round is for (`--findings`). It
|
||||
buys the stopped review's fix round: one scoped fix-check of the PR's own
|
||||
change since the stop's head (a base merge in between is not part of it), in
|
||||
the same run or a new one on another machine, never a new full review.
|
||||
Step 1's `PR_REVIEW_FLAGS:` adds `--round-grant <id> --stop <head>` and the
|
||||
route is `fix-check`. It answers only the newest stop record, and nothing
|
||||
once another run reviewed after that stop, HEAD no longer contains the stop's
|
||||
head, or another run claimed it (`PR_REVIEW_GRANT: not applied (why)`).
|
||||
A fix-check found nothing to read (an empty, reverted or base-only change)
|
||||
plans no fix-check. The fix-check never earns another: a blocker there
|
||||
stops with `PR_ROUND_CAP` again.
|
||||
- **`--kind extra-round`, before review.** One round past the cap, with its fix
|
||||
round, at a head no review has stopped at: instead of the read-only review.
|
||||
Step 1's `PR_REVIEW_FLAGS:` adds `--round-grant <id>` when the grant names
|
||||
HEAD, or a head HEAD only merges the base into with the PR's own added and
|
||||
removed lines byte-identical and in the same places (preflight merges the base
|
||||
first); the plan raises that run's cap by one round, keeps the round's fix
|
||||
round, and keeps the grant after the fix round's commits move HEAD past it.
|
||||
An extra-round grant never answers a stop.
|
||||
A run whose flags name a grant runs `gstack-ship-receipt claim` before its
|
||||
first dispatch, which writes a grant record into the runs block; a grant
|
||||
another run claimed is refused (`GRANT_SPENT`), a voided run's claim still
|
||||
spends it, and stop and grant records are never trimmed from the block.
|
||||
gstack never grants itself a round: `--by` naming gstack (any name starting
|
||||
with "gstack", so a Captain called GStack Minder writes "Captain GStack
|
||||
Minder") and a grant from inside an open `/ship` run are refused, and `add`
|
||||
refuses the scope. `--by` is otherwise the caller's own text, recorded and
|
||||
not checked: a lane that records a grant (or a ruling) from another checkout
|
||||
under its Captain's name can't be told apart from the Captain doing it, so the
|
||||
Captain's check of the receipt's `review_round_grants` and the PR body's lines
|
||||
is the control. The receipt lists grants under `review_round_grants`.
|
||||
|
||||
<a id="transitions"></a>
|
||||
### Transitions
|
||||
|
||||
+55
-8
@@ -7427,16 +7427,63 @@ final head; this stop then means that review found a blocker or a gate-class edi
|
||||
`PR_REVIEW_FLAGS:`. A fix below the blocking floor finishes with its notes
|
||||
listed instead of stopping.
|
||||
|
||||
**Fix.** The lane's Captain decides. Ship with the open notes listed, or, when a finding above the floor is
|
||||
open in this PR's own change or the design changed, have the lane or Captain
|
||||
record one round with the command the `NEXT:` line prints,
|
||||
`gstack-approvals round-grant --pr <n> --head <sha> --kind extra-round --reason
|
||||
<why> --by <lane or Captain>`, then rerun `gstack-ship-preflight`: its
|
||||
`PR_REVIEW_FLAGS:` line adds `--round-grant <id>` for the plan.
|
||||
The grant names one head; a new push needs a new grant. This is not an owner
|
||||
ask, and gstack cannot grant itself one (`--by gstack` is refused)
|
||||
**Fix.** The lane's Captain decides. Ship with the open notes listed, park, or,
|
||||
when a finding above the floor is open in this PR's own change, buy the stopped
|
||||
review's fix round:
|
||||
|
||||
1. Record the stop: `gstack-ship-receipt stop --pr <n> --run <the /ship run>
|
||||
--since <REVIEW_SINCE>` (`/ship` runs it on `NEXT: stop`). It prints
|
||||
`STOP_RECORD:` and the grant command.
|
||||
2. The lane or Captain records that grant: `gstack-approvals round-grant --pr
|
||||
<n> --head <the stop's head> --kind fix-check --stop-run <its run> --findings
|
||||
<the open finding ids> --reason <why> --by <lane or Captain>`.
|
||||
3. Commit the fix on top of the stop's head. A new run's `gstack-ship-preflight`
|
||||
prints `PR_REVIEW_FLAGS:`; the same run, whose preflight already ran, gets
|
||||
that line from `gstack-ship-receipt history --pr <n> --base <base> --run
|
||||
<the /ship run>`. It adds `--round-grant <id> --stop <head>`, and the plan is one scoped fix-check of the PR's own change
|
||||
since that head, with no new full review. The run claims the grant first
|
||||
(`gstack-ship-receipt claim`).
|
||||
|
||||
A head no review has stopped at takes an `--kind extra-round` grant instead:
|
||||
one full round with its fix round. Each grant is spent by the one run that
|
||||
claims it. When `PR_REVIEW_GRANT: not applied (...)` prints, the reason names
|
||||
what doesn't match (another stop or head, a stale stop, a claimed grant). This
|
||||
is not an owner ask, and gstack cannot grant itself one (`--by` naming gstack
|
||||
is refused) ([review-policy.md](review-policy.md#rounds-per-pull-request)).
|
||||
|
||||
<a id="stop-unbound"></a>
|
||||
### `STOP_UNBOUND`
|
||||
|
||||
**Meaning.** `gstack-ship-receipt stop` found no review of this run that
|
||||
gstack can tie to one commit: the newest `via:ship` review row since
|
||||
`--since` is missing, didn't finish, read a tree that moved or wasn't
|
||||
committed, or its commit isn't HEAD or under it. It recorded no stop record, so
|
||||
no fix-check grant can buy that review's fix round.
|
||||
|
||||
**Fix.** Nothing for a grant to answer. The lane's Captain ships with the open
|
||||
notes listed or parks; a fresh `/ship` run gives the head its review
|
||||
([review-policy.md](review-policy.md#rounds-per-pull-request)).
|
||||
|
||||
<a id="grant-spent"></a>
|
||||
### `GRANT_SPENT`
|
||||
|
||||
**Meaning.** `gstack-ship-receipt claim` found another `/ship` run's grant
|
||||
record for this round grant in the PR body's runs block. A grant buys one round,
|
||||
and a voided run's claim still spends it.
|
||||
|
||||
**Fix.** Record a new grant for the stop the PR is at now; `gstack-ship-receipt
|
||||
stop` prints the command ([troubleshooting](#pr-round-cap)).
|
||||
|
||||
<a id="grant-unknown"></a>
|
||||
### `GRANT_UNKNOWN`
|
||||
|
||||
**Meaning.** `gstack-ship-receipt claim --grant <id>` found no approved
|
||||
`review_round_grant` row with that id in the branch's approval record or its
|
||||
mirror.
|
||||
|
||||
**Fix.** Pass the id `gstack-approvals round-grant` printed, from a checkout
|
||||
that sees that record ([troubleshooting](#pr-round-cap)).
|
||||
|
||||
<a id="receipt-prose-mismatch"></a>
|
||||
### `RECEIPT_PROSE_MISMATCH`
|
||||
|
||||
|
||||
Reference in new issue
Block a user