From caa7140eee62a621c9932b97df5d1362c9e87622 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 15 Nov 2026 10:06:53 +0800 Subject: [PATCH] Explain in CONTRIBUTING how outside reports and PRs land (GST-2723) (#4374) * Explain in CONTRIBUTING how outside reports and PRs land (GST-2723) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Fix contributor-docs wording found in review Review-Finding: p1/specialist-batched#1 reader=security Review-Finding: p1/specialist-batched#2 reader=red-team Review-Finding: p1/adversarial-native#5 reader=adversarial-native Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Say in the review policy that docs-only outside PRs are not rewritten Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- CONTRIBUTING.md | 100 +++++++++++++++------- captain/SKILL.md | 3 +- captain/SKILL.md.tmpl | 3 +- captain/templates/CREW.md | 5 +- changelog.d/docs-outside-contributions.md | 1 + crew/docs/captain.md | 27 ++++-- crew/docs/recommended-harness.md | 2 +- docs/review-policy.md | 4 +- docs/triage.md | 4 +- 9 files changed, 102 insertions(+), 47 deletions(-) create mode 100644 changelog.d/docs-outside-contributions.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef2f64594..42db0bdc3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -922,44 +922,79 @@ triaging for the maintainer posts these comments under its bot identity `gh` runs as the maintainer. The full rule, including the labels and the close reasons, is in [docs/triage.md](docs/triage.md). -## Community PR triage (wave process) +## Sending a report or a PR -When community PRs accumulate, batch them into themed waves: +gstack is maintained day to day by AI agents working for Garry Tan. They triage issues +and PRs, rebuild good patches on current main, and land them with the author credited. +That's why nearly every commit on main reads as Garry's: the agents commit under his +account, and your credit is a `Co-authored-by:` trailer plus a line in the PR body. -1. **Categorize** — group by theme (security, features, infra, docs) -2. **Deduplicate** — if two PRs fix the same thing, pick the one that - changes fewer lines. Close the other with a note pointing to the winner. -3. **Collector branch** — create `pr-wave-N`, merge clean PRs, resolve - conflicts for dirty ones, verify with `bun run test && bun run build` -4. **Close with context** — every closed PR gets a comment explaining - why and what (if anything) supersedes it. Contributors did real work; - respect that with clear communication. An agent running the wave posts - these notes under its bot identity, never the maintainer's own account. -5. **Ship as one PR** — single PR to main with all attributions preserved - in merge commits. Include a summary table of what merged and what closed. +**What happens to your PR.** Outside code is treated as untrusted: an agent reads your +diff as text and never checks it out, runs it or builds it. Then one of three things +happens. -See [PR #205](../../pull/205) (v0.8.3) for the first wave as an example. +- **Docs for people only** (for example the README) can be merged as + they are, after an agent checks every link, command and install step in them against + main. +- **A small fix** that is plainly correct, about 40 lines or fewer not counting its + tests, is taken even when the gain is small. An agent rebuilds it on current main + with you as co-author. We land at most one of these a day. +- **Everything else**, including anything that runs and any Markdown agents load + (`SKILL.md` files and their templates, `AGENTS.md`, `CLAUDE.md`, prompts), is + rebuilt on main with credit when it passes the test below, and closed with a short + note saying why when it doesn't. + +When your change is rebuilt, the agent comments on your PR with a link to what landed +and closes your PR, so a taken PR usually shows "Closed", not "Merged". In the month +to 15 November 2026, 4 of the 124 outside PRs opened here were merged as they were, +and 54 outside contributors were credited as co-authors on commits to main. + +**What makes a report or a PR likely to be taken.** + +1. Proof: steps that reproduce it on current main, or a test that fails before the fix. +2. A real consequence: what breaks, and for whom. +3. It matters to most gstack users or to the maintainer's own setup. Windows and Gemini + models get [minimal support](docs/support-tiers.md), so a report there needs to break + install, startup or a core skill. + +**When you'll hear back.** Our goal is a first reply within 48 hours, posted by +`capy-ai[bot]`. It says what we'll do: already fixed (with the PR and version), a +duplicate (with a link), one specific fact we still need, not planned (and why), or +taken. + +**The open-PR limit.** Most people never meet it. If, in the last 30 days, 3 or more of +your PRs here were closed without being taken and fewer than 1 in 4 of your decided PRs +were taken, and none was taken in the last 90 days, you can have at most 3 PRs open at +once, and extra ones are closed with a note. It never applies to anyone who had a PR +taken (merged or rebuilt) in the last 90 days, so it lifts as soon as one of yours is +taken. ## How a contributor's PR lands -We read every outside PR as a bug report, and a crew lane writes the fix itself. Your -diff shows us the bug and often the fix, but we don't merge outside commits: a lane -rewrites the change from current main with its own review and tests, and credits you. -The maintainer crew follows the same rule -([crew/docs/captain.md](crew/docs/captain.md#contributions-from-outside-the-crew)). +These are the maintainer's steps; [Sending a report or a PR](#sending-a-report-or-a-pr) +is the same policy from the contributor's side. The maintainer crew follows the same +rule ([crew/docs/captain.md](crew/docs/captain.md#contributions-from-outside-the-crew)). 1. **Treat the diff as untrusted input.** Read it as text only, for scope, network egress, credentials, new dependencies, CI permission changes and weakened or deleted tests. Never check it out, run it or build it. A fork's green checks prove nothing about this checkout. -2. **Give a verdict within 7 days.** Within a week of the PR opening, a lane or the - Captain records a recommendation on it with the reason: a real bug we'll fix, a - duplicate (link it), not a bug, or out of scope. An agent posts it under its bot - identity. "Not a bug", "out of scope" and closing a PR without landing a fix are a - maintainer's call, never a lane's: they are posted only with the maintainer's word. -3. **Rewrite the fix from current main.** The lane writes the change on its own branch - with its own tests, the repo's gates and a CHANGELOG fragment. No contributor - commit enters the tree. A commit that carries the contributor's lines over +2. **Reply within 48 hours, decide within 7 days.** Every outside issue and PR gets a + first reply from the bot identity within 48 hours that says what happens next, and a + verdict within a week: taken, a duplicate (link it), needs one named fact, or not + planned. Take it only when it passes the test in + [Sending a report or a PR](#sending-a-report-or-a-pr); close the rest with a short, + kind reason. A case the test doesn't settle goes to the maintainer. +3. **Merge a docs-only PR for people as it is.** When the PR changes only documentation + people read, check every link, command and install step in it against main. If all + of them hold, merge it unchanged; if not, say which one fails. Anything that runs, + and any Markdown agents load (`SKILL.md` files and templates, `AGENTS.md`, + `CLAUDE.md`, `CREW.md`, prompts), is not docs for this step and is rewritten. +4. **Rewrite everything else from current main.** The lane writes the change on its own + branch with its own tests, the repo's gates and a CHANGELOG fragment. No contributor + commit enters the tree. A plainly correct fix of about 40 lines or fewer (counting + the fix, not its tests) is taken even when the gain is small, at most one such PR a + day. A commit that carries the contributor's lines over unchanged gets a `Co-authored-by:` trailer for them. Fetch their PR head as a ref without checking it out (`git fetch origin +pull//head:refs/contrib/`; the `+` lets a re-fetch follow a force-push), then run @@ -968,17 +1003,22 @@ The maintainer crew follows the same rule no co-author. A fork's commits can name anyone, so keep only the authors whose lines you carry: drop the rest with `--exclude ` when you rerun it with `--message `. Never guess an email: use the identity on their commits. -4. **Credit them in the fix.** The PR body names the original PR and its author in +5. **Credit them in the fix.** The PR body names the original PR and its author in the first paragraph and says what differs from their diff. The CHANGELOG fragment thanks them by handle. -5. **Close the original with a specific thank-you.** After the fix lands, comment on +6. **Close the original with a specific thank-you.** After the fix lands, comment on their PR with what landed (the PR number and version), what changed from their diff and why, and thank them by name for the specific thing they found. Then close it. An agent posts that comment under its bot identity, never the maintainer's own account. +7. **Apply the open-PR limit only to chronic authors.** An author is capped at 3 open + PRs only when, in the last 30 days, 3 or more of their PRs closed untaken and fewer + than 1 in 4 of their decided PRs were taken, and none of their PRs was taken in the + last 90 days. Taken means merged, or rebuilt by the crew. Close the extra PRs with a + note that names the limit and says it lifts once one of their PRs is taken. If we won't fix what the PR reports, say why on the PR and close or park it under -[Issue triage](#issue-triage), with the maintainer's word. +[Issue triage](#issue-triage). ## Upgrade migrations diff --git a/captain/SKILL.md b/captain/SKILL.md index 2d6544b84..b10edc5ab 100644 --- a/captain/SKILL.md +++ b/captain/SKILL.md @@ -430,7 +430,8 @@ of 3 to 6, each with an integrator who runs `wave build`, /ship once and READY o PR: one slot, one version. Constituent heads freeze, `--drop` sends a changed one back to its owner, and `wave settle` closes the rest after the merge (docs/ship-policy.md#wave-prs). Credit every contributor (`Contributed by @handle`, `Co-authored-by`), and never merge a -contributor's PR directly from its fork. +contributor's PR directly from its fork unless it changes only docs people read and a text +read checked every link, command and install step. ## Where the protocols differ, ship both diff --git a/captain/SKILL.md.tmpl b/captain/SKILL.md.tmpl index 19a10af26..ae8ea7053 100644 --- a/captain/SKILL.md.tmpl +++ b/captain/SKILL.md.tmpl @@ -358,7 +358,8 @@ of 3 to 6, each with an integrator who runs `wave build`, /ship once and READY o PR: one slot, one version. Constituent heads freeze, `--drop` sends a changed one back to its owner, and `wave settle` closes the rest after the merge (docs/ship-policy.md#wave-prs). Credit every contributor (`Contributed by @handle`, `Co-authored-by`), and never merge a -contributor's PR directly from its fork. +contributor's PR directly from its fork unless it changes only docs people read and a text +read checked every link, command and install step. ## Where the protocols differ, ship both diff --git a/captain/templates/CREW.md b/captain/templates/CREW.md index 47c523752..eb931330f 100644 --- a/captain/templates/CREW.md +++ b/captain/templates/CREW.md @@ -108,8 +108,9 @@ Homes are paths in the gstack checkout the lane checked at session start. 17. **New files follow `REPO_CONVENTIONS`.** Home: the repository's AGENTS.md. -18. **Outside PRs are bug reports.** A verdict within 7 days; a real bug is rewritten on - main with credit, and no contributor commit enters the tree. Home: `crew/docs/captain.md` +18. **Outside PRs are bug reports.** A reply within 48 hours and a verdict within 7 days; + a real fix is rewritten on main with credit. Only a docs-only PR for people merges as + it is, after a text read of every link, command and install step. Home: `crew/docs/captain.md` (Contributions from outside the crew). 19. **CHANGELOG-only conflicts** are the train's, not yours (folded into 14). Home: diff --git a/changelog.d/docs-outside-contributions.md b/changelog.d/docs-outside-contributions.md new file mode 100644 index 000000000..7c28f9541 --- /dev/null +++ b/changelog.d/docs-outside-contributions.md @@ -0,0 +1 @@ +- **CONTRIBUTING.md now says plainly how outside reports and PRs land.** It explains that AI agents working for the maintainer triage, rebuild and land outside patches with the author credited, which is why commits read as the maintainer's. It lists the three paths a PR can take (a docs-only PR for people can merge as it is after its links, commands and install steps are checked; a plainly correct fix of about 40 lines is taken even when small; everything else is rebuilt on main when it has proof, a real consequence and matters to most users), the 48-hour first-reply goal, and the narrowed open-PR limit, which never applies to anyone with a PR taken in the last 90 days. The stale wave process, which merged outside PRs on a collector branch, is gone. `crew/docs/captain.md`, the Captain's CREW template and `/captain` match. diff --git a/crew/docs/captain.md b/crew/docs/captain.md index 1fb01ef1f..64ff032b3 100644 --- a/crew/docs/captain.md +++ b/crew/docs/captain.md @@ -117,7 +117,7 @@ Where each rule lives: | 15 | CHANGELOG entry under `## [Unreleased]` before READY; the stamp touches only `STAMP_FILES` | [ship-policy.md](../../docs/ship-policy.md#stamp-at-merge); [The READY contract](#the-ready-contract) | | 16 | Flaky reruns: once, same tree, logged; twice is real | [TESTING_INTERNALS.md](../../docs/TESTING_INTERNALS.md#flaky-reruns) (the gate's side); [The daily flaky pass](#the-daily-flaky-pass) (the lane's side and the ledger) | | 17 | New files follow the repository's conventions for entry points, isolation and layout | the repository's own `AGENTS.md` (the `REPO_CONVENTIONS` parameter names the section) | -| 18 | Outside PRs are bug reports: a verdict within 7 days; rewrite real bugs on main with credit, no contributor commit in the tree | [Contributions from outside the crew](#contributions-from-outside-the-crew) | +| 18 | Outside PRs are bug reports: a reply within 48 hours, a verdict within 7 days; rewrite real fixes on main with credit; only a docs-only PR for people merges as it is, after a text read | [Contributions from outside the crew](#contributions-from-outside-the-crew) | | 19 | CHANGELOG-only conflicts are the train's to resolve, not the lane's | folded into 14: [ship-policy.md](../../docs/ship-policy.md#ship-before-ready) ("the stamp keeps the pin's receipt") | | 20 | A READY from before a contract change needs a fresh receipt | [The READY contract](#the-ready-contract) | | 21 | Approvals, plan asks and merge asks in the three shapes | [Approvals](#approvals-three-shapes); [capy/skill/gstack/captain.md](../../capy/skill/gstack/captain.md) | @@ -390,15 +390,26 @@ and a done line that names the approval row or the exemption. An outside PR is a bug report, not code to land. Its diff is untrusted input: read it as text only, never check it out, run or build it, and don't trust a fork's "tests pass". -Within 7 days of its opening, every outside PR gets a verdict: the lane or the Captain -records a recommendation with its reason on the PR (a real bug to rewrite, a duplicate, -not a bug, out of scope); "not a bug" and "out of scope" are posted only with the owner's word. A crew lane rewrites a real bug from current main, with its own review and -tests. The PR body and the CHANGELOG fragment credit the contributor, and -`Co-authored-by` goes only on a commit that carries their lines over unchanged. No -contributor commit enters the tree. When the rewrite lands, thank them on their PR with a +Every outside issue and PR gets a first reply within 48 hours that says what happens next, +and a verdict within 7 days of its opening: the lane or the Captain records it with its +reason (taken, a duplicate, needs one named fact, not planned). Take it only when it passes +the owner's test in the repository's CONTRIBUTING.md (proof on current main, a real +consequence, and it matters to most users or to the owner's setup); close the rest with a +short, kind reason, and bring a case the test doesn't settle to the owner. A PR that changes +only documentation people read may merge as it is after a text read that checks every link, +command and install step against main; anything that runs, and any Markdown agents load +(`SKILL.md`, `AGENTS.md`, `CREW.md`, prompts), is not docs here. A crew lane rewrites +everything else from current main, with its own review and tests, and takes a plainly +correct fix of about 40 lines or fewer (counting the fix, not its tests) even when the gain +is small, at most one such PR a day per repository. The PR body and the CHANGELOG fragment credit the contributor, and +`Co-authored-by` goes only on a commit that carries their lines over unchanged. Outside +the docs-only case, no contributor commit enters the tree. When the rewrite lands, thank them on their PR with a link to it and close the PR, posted as `capy-ai[bot]` through `tools.pr.comment`, never `gh pr comment`, `gh issue comment` or `gh api` (`gh` runs as the owner). Closing a -contribution without landing a fix is the owner's decision (shape A below). The +contribution without landing a fix is the owner's decision, made once as the test above +(shape A below). Only a chronic author is limited to 3 open PRs: 3 or more PRs closed +untaken in 30 days, fewer than 1 in 4 taken, and none taken (merged or rebuilt) in the +last 90 days; the note that closes an extra PR says the limit lifts once one is taken. The repository's own statement of these steps is [CONTRIBUTING.md](../../CONTRIBUTING.md#how-a-contributors-pr-lands). diff --git a/crew/docs/recommended-harness.md b/crew/docs/recommended-harness.md index 1ae2ee69f..c484e7282 100644 --- a/crew/docs/recommended-harness.md +++ b/crew/docs/recommended-harness.md @@ -353,7 +353,7 @@ on a few points. Ship the one that fits the repository; both are supported. | Small fixes | one PR each, batched by the train | batched into wave PRs, since serial slots cost about 30 minutes each | | After the merge | the main backstop gates any push a train did not cover, and freezes the queue on red | the controller watches main's test, e2e and release runs until the release publishes; a red main freezes the queue until root-caused | | Severe triage | the Captain watches issues and PRs and starts a thread per unowned severe item | a scheduled severe sweep (every 4 to 8 hours) with a fixed severity bar, dedupe against owned lanes, one hotfix thread per batch | -| Contributor PRs | read as bug reports and rewritten from main on a crew branch, so no contributor commit enters the tree; `Co-authored-by` only on lines carried over unchanged; the fork PR is closed with a thank-you that links the fix, posted as `capy-ai[bot]` through `tools.pr.comment`, never `gh` | the rewritten fixes land through a wave PR with "Contributed by @handle" and `Supersedes` lines, `Co-authored-by` only on lines carried over unchanged | +| Contributor PRs | read as bug reports and rewritten from main on a crew branch, so no contributor commit enters the tree, except a docs-only PR for people, merged as it is after a text read of every link, command and install step; `Co-authored-by` only on lines carried over unchanged; the fork PR is closed with a thank-you that links the fix, posted as `capy-ai[bot]` through `tools.pr.comment`, never `gh` | the rewritten fixes land through a wave PR with "Contributed by @handle" and `Supersedes` lines, `Co-authored-by` only on lines carried over unchanged | | Privacy | the pregate's sealed-output and secret scans before every push | plus a per-user denylist grep (names, hostnames, identifying counts from private sources) before any public artifact | ## Known Capy limits diff --git a/docs/review-policy.md b/docs/review-policy.md index 7efe68428..12b8d0eab 100644 --- a/docs/review-policy.md +++ b/docs/review-policy.md @@ -859,8 +859,8 @@ and a later reader agree on what was flagged: ## Crediting a contributor's lines -Outside PRs are rewritten from main rather than ported -([CONTRIBUTING.md](../CONTRIBUTING.md#how-a-contributors-pr-lands)). When a rewrite +Outside PRs, other than docs-only PRs for people, are rewritten from main rather than +ported ([CONTRIBUTING.md](../CONTRIBUTING.md#how-a-contributors-pr-lands)). When a rewrite carries a contributor's lines over unchanged, the commit that carries them credits them. Pass the contributor's PR commits as the range, fetched as a ref and never checked out (`git fetch origin +pull//head:refs/contrib/`, then `origin/..refs/contrib/`; diff --git a/docs/triage.md b/docs/triage.md index 3b0d30a87..e4e612fc9 100644 --- a/docs/triage.md +++ b/docs/triage.md @@ -94,7 +94,7 @@ shape, customization and localization, retro, and CI supply chain. Parked bugs sit under "parked in Wave 9" in the same file. Pick a theme up as a whole and credit every linked reporter in the CHANGELOG entry. -Community pull requests follow the wave process in -[CONTRIBUTING.md](../CONTRIBUTING.md#community-pr-triage-wave-process); a +Community pull requests follow +[How a contributor's PR lands](../CONTRIBUTING.md#how-a-contributors-pr-lands); a closed PR gets the same courtesy as a closed issue: a comment saying why and what supersedes it.