heavy-duty/cast
7
0
Fork 0
Code Issues 4 Pull requests Projects Releases 3 Packages Wiki Activity Actions

Merge pull request #130 from dan-claude-bot/docs/contributing-blocker-axis

Browse source 
docs(contributing): document the blocker axis and merge-next ownership
This commit is contained in:
Daniel Marin 2026-07-20 20:07:22 +01:00 committed by GitHub
commit 715530780b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 10 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
CONTRIBUTING.md
View file

@ -32,10 +32,13 @@ labels tell you where everything is without opening anything.
maintainer's review (step 6), and the reconciler flips the label on that maintainer's review (step 6), and the reconciler flips the label on that
request, because an explicit request is a fact it can trust. request, because an explicit request is a fact it can trust.
6. **When the round passes, the author hands the PR to the maintainer** by 6. **When the round passes, the author hands the PR to the maintainer** by
requesting their review — that request is what flips `state:needs-human`. requesting their review — that request is what flips `state:needs-human`,
With three formal head-current approvals the labels workflow requests it provided the PR carries **no `blocker:*` label**. A blocker means the work
automatically; when part of the panel is comment-only, reading their is still yours whatever the round said, so a request on a conflicted or red
agreement is the author's judgment, so the author makes the request. PR will not flip it. With three formal head-current approvals the labels
workflow requests the maintainer automatically; when part of the panel is
comment-only, reading their agreement is the author's judgment, so the
author makes the request.
7. **Checks must be green**: `npm run check`, `npm run build`, and 7. **Checks must be green**: `npm run check`, `npm run build`, and
`npm test` locally mirror what CI runs. `npm test` locally mirror what CI runs.
8. **Feature PRs land their changelog entry as part of the PR** (box's 8. **Feature PRs land their changelog entry as part of the PR** (box's
@ -108,11 +111,13 @@ machine-owned label just gets corrected on the next pass:
| Labels | Set by | | Labels | Set by |
|---|---| |---|---|
| `state:*` | the labels workflow ([.github/workflows/labels.yml](.github/workflows/labels.yml)) — recomputed from GitHub's own facts every 15 minutes and on PR events. Never by hand. | | `state:*` | the labels workflow ([.github/workflows/labels.yml](.github/workflows/labels.yml)) — recomputed from GitHub's own facts every 15 minutes and on PR events. Never by hand. Exactly one per PR: *whose ball is it.* |
| `blocker:*` | the same workflow, from the same facts — *what is in the way.* Any number per PR, or none. Never by hand: applying one does not stop a merge, and removing one does not unblock anything. Fix the thing and the next sweep drops the label. |
| `stale` | the same workflow — 48h without commits, comments, or reviews. `blocked` PRs are exempt: they are quiet legitimately. | | `stale` | the same workflow — 48h without commits, comments, or reviews. `blocked` PRs are exempt: they are quiet legitimately. |
| `scope:*` on PRs | actions/labeler, from the changed paths ([.github/labeler.yml](.github/labeler.yml)). Additive — you may add more, the machine won't remove them. | | `scope:*` on PRs | actions/labeler, from the changed paths ([.github/labeler.yml](.github/labeler.yml)). Additive — you may add more, the machine won't remove them. |
| `scope:*` on issues | you, when opening or triaging — issues have no paths to derive from. | | `scope:*` on issues | you, when opening or triaging — issues have no paths to derive from. |
| `blocked`, `release` | you — automation never guesses intent. | | `blocked`, `release` | you — automation never guesses intent. |
| `merge-next` | you or the agent owning the queue. Which PR lands first is a judgement about how they conflict, so the workflow never sets it — it only **clears** it, the moment the PR stops being something a human could merge. |
| `bug` / `enhancement` / `documentation` | you, on issues only — a PR's type already lives in its title. | | `bug` / `enhancement` / `documentation` | you, on issues only — a PR's type already lives in its title. |
## Issues ## Issues