From e802fa0c4ee4f333434639b3de3dd275eab362f0 Mon Sep 17 00:00:00 2001 From: Jim Wordelman Date: Mon, 6 Jul 2026 22:12:29 -0700 Subject: [PATCH] docs: add CONTRIBUTING_PR_GUIDELINES.md (codify reviewer expectations for contributors) (#3913) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: add CONTRIBUTING_PR_GUIDELINES.md (codify reviewer expectations for contributors) Co-Authored-By: Claude Sonnet 4.6 * chore: release gate PASS for be-z33z (CONTRIBUTING_PR_GUIDELINES docs) Docs-only PR #3913. Review be-z33z PASS. CI 18/18 non-skipped SUCCESS. Co-Authored-By: Claude Sonnet 4.6 * chore: retrigger CI (unrelated audit flake on prior run) Prior run failed only on internal/audit::TestAppend_ConcurrentWritersUniqueIDs, a birthday-paradox flake in 32-bit newID() — see be-5uxe for the source fix. This commit is intentionally empty to retrigger CI on this docs-only PR. --------- Co-authored-by: Jim Wordelman Co-authored-by: Claude Sonnet 4.6 Co-authored-by: matt wilkie --- CONTRIBUTING_PR_GUIDELINES.md | 39 +++++++++++++++++++++++++++++++++++ release-gates/be-z33z-gate.md | 19 +++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 CONTRIBUTING_PR_GUIDELINES.md create mode 100644 release-gates/be-z33z-gate.md diff --git a/CONTRIBUTING_PR_GUIDELINES.md b/CONTRIBUTING_PR_GUIDELINES.md new file mode 100644 index 000000000..40b012cbe --- /dev/null +++ b/CONTRIBUTING_PR_GUIDELINES.md @@ -0,0 +1,39 @@ +# Contributor PR Guidelines + +This is the source of truth for agents and humans filing pull requests to beads. + +## Philosophy + +beads is small and clean. PRs that respect the existing layering land fastest. The codebase has clear layers — schema, storage/issueops, application (cmd/bd) — and the reviewer optimizes for keeping those layers clean and the diff reviewable. The most common rejection reasons are fixable before opening a PR. + +## Before Opening a PR + +**Prove the bug in beads itself.** Include a beads-only minimal repro test or benchmark that demonstrates the bug or performance regression exists with stock beads and no orchestrator (no gascity, no factory, no external agent framework). Without this, the PR will likely be rejected as an orchestrator bug. + +**Verify with stock beads.** Before claiming any bug, reproduce it with no orchestrator running. Many apparent beads bugs turn out to be orchestrator-layer issues. + +**Add benchmarks for performance claims.** If your PR claims a speedup, include a bench test that shows it. The reviewer will not assume the new code is faster. + +## Sizing and Scoping + +**One layer per PR.** If a fix needs changes at both the storage/issueops layer and the application (cmd/bd) layer, file them as separate stacked PRs: the storage primitive first, then the application wiring on top. + +**Stack when a fix spans layers.** A PR that touches issueops primitives AND cmd/bd code at the same time is hard to review. Split it. The primitive PR unblocks the application PR. + +**Keep diffs reviewable.** If your PR is over a few hundred lines, look for ways to split it. A 13K-line diff will not be reviewed. + +## Layering Rules + +**Primitives at the lowest layer first.** New capabilities belong at storage/issueops before the application calls them. If you are adding a new query, add it to issueops first, expose it on the storage.Storage interface, and implement it there. The application layer (cmd/bd) then calls the new method without reaching across layers itself. + +**Do not reach across layers from above.** If cmd/bd is doing SQL-like work that belongs in issueops, that is a sign the abstraction boundary is wrong. File a storage primitive PR first. + +## Code Style + +**Minimize inline code comments.** The reviewer routinely asks for inline comments to be removed. Let the commit message and PR description carry the why. Use comments only for non-obvious invariants that cannot be expressed in the code itself. + +**Commit messages over inline comments.** If you feel the need to explain a block of code with a comment, write that explanation in the commit message instead. + +## When in Doubt + +Read PR_MAINTAINER_GUIDELINES.md to understand what the maintainer optimizes for — it explains the review philosophy, triage groups, and outcome types. Understanding the maintainer perspective makes it easier to anticipate feedback before opening a PR. diff --git a/release-gates/be-z33z-gate.md b/release-gates/be-z33z-gate.md new file mode 100644 index 000000000..afc3495b1 --- /dev/null +++ b/release-gates/be-z33z-gate.md @@ -0,0 +1,19 @@ +# Release gate: be-z33z — CONTRIBUTING_PR_GUIDELINES.md (PR #3913) + +- **Bead:** be-z33z (Review: CONTRIBUTING_PR_GUIDELINES.md, PR #3913) +- **Branch:** `docs/be-ad6qbk-contributing-pr-guidelines` +- **Head commit:** `2bbcc1f9d` — docs: add CONTRIBUTING_PR_GUIDELINES.md (codify reviewer expectations for contributors) +- **Evaluated:** 2026-05-19 by beads/deployer + +## Gate criteria + +| # | Criterion | Result | Evidence | +|---|-----------|--------|----------| +| 1 | Review PASS present | **PASS** | be-z33z notes: "Review verdict: PASS. Docs-only PR... Content is accurate and matches observed reviewer expectations. No security surface, no code change. Routing to deployer." | +| 2 | Acceptance criteria met | **PASS** | `docs/CONTRIBUTING_PR_GUIDELINES.md` added (39 lines); `PR_MAINTAINER_GUIDELINES.md` cross-reference valid | +| 3 | Tests pass | **PASS** | CI 18/18 non-skipped SUCCESS, 3 SKIPPED (Embedded Dolt build/test jobs expected skip for docs-only PR) | +| 4 | No high-severity review findings open | **PASS** | 0 findings in be-z33z | +| 5 | Final branch is clean | **PASS** | `git status` clean | +| 6 | Branch diverges cleanly from main | **PASS** | 1 commit ahead of base (no conflicts) | + +## Verdict: PASS