From f285cc77115372ce627798fa1ff945029915da89 Mon Sep 17 00:00:00 2001 From: ccross Date: Tue, 7 Jul 2026 17:32:16 -0400 Subject: [PATCH] =?UTF-8?q?docs(governance):=20frame=20PRs=20as=20"push=20?= =?UTF-8?q?requests"=20=E2=80=94=20problem-first=20evaluation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refines the OSS contribution docs around the mindset that a pull request is a request to push a change, evaluated by "what problem does this solve?" before the diff. - PR template: leads with "What problem does this solve?" (was "what does this PR do?"); adds a DCO sign-off checklist item. - CONTRIBUTING.md: new "How we evaluate a PR" section — the 5-rung ladder (problem -> scope -> solution -> verifiable -> governance); line-by-line review comes after the top three. - ADR 010: adds decision 9 (Problem-First PR Triage) codifying the ladder as the governance evaluation procedure, so review is consistent and delegable. Docs-only; no code or product change. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_012wU47GVzskAummZqgH6FgF --- .github/pull_request_template.md | 20 ++++++++----- CONTRIBUTING.md | 14 +++++++++ ...010-open-source-contribution-governance.md | 29 ++++++++++++++++++- 3 files changed, 55 insertions(+), 8 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 32c6c2d..2309c38 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,3 +1,9 @@ +## What problem does this solve? + + + ## Type @@ -7,23 +13,23 @@ - [ ] Documentation - [ ] Other: -## Description +## What this changes - + ## Testing - + ## Checklist - [ ] `cargo fmt --all -- --check` passes - [ ] `cargo clippy --workspace -- -D warnings` passes - [ ] `cargo test --workspace` passes -- [ ] No new warnings introduced +- [ ] Commits are signed off (`git commit -s`) per the DCO - [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md) ## Breaking changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e6eec2..72f6041 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -174,6 +174,20 @@ ideas are bad. If you want gestures or voice on Linux, watch the [Esver OS](http --- +## How we evaluate a PR + +A pull request is a request to push a change — we read it from the problem down, not the diff up. In order: + +1. **What problem does it solve?** No stated problem, or a solution hunting for one, gets "what's the problem here?" before any code review. +2. **Is the problem in scope?** See [what we will NOT merge](#what-we-will-not-merge). Out of scope → we decline with the boundary, not the code. +3. **Is it the right solution?** A real, in-scope problem can still have the wrong fix — we look for the simplest approach that fits the architecture. +4. **Is it verifiable?** Evidence it works (tests, `visage discover` output, a repro) and green CI. +5. **Governance** — DCO sign-off, extra review for the auth path, attribution. + +Line-by-line review comes after 1–3. So the fastest path to merge is a clear problem statement — and a well-scoped PR gets a fast yes or a fast, kind no, never silence. + +--- + ## PR guidelines All PRs are filed against `main`. Use the [PR template](.github/pull_request_template.md) diff --git a/docs/decisions/010-open-source-contribution-governance.md b/docs/decisions/010-open-source-contribution-governance.md index 3900d36..f9170d9 100644 --- a/docs/decisions/010-open-source-contribution-governance.md +++ b/docs/decisions/010-open-source-contribution-governance.md @@ -3,6 +3,7 @@ **Date:** 2026-02-24 **Status:** Accepted **Deciders:** Sovren Software core team +**Amended:** 2026-07-07 — added §9 (Problem-First PR Triage) --- @@ -113,7 +114,7 @@ Three issue templates and one PR template standardize contribution quality: | Bug report | Structured: environment, repro steps, expected/actual, logs | | Hardware report | Mirrors Adopt-a-Laptop format — device info, test results, discovery output | | Feature request | Includes scope-check reminder linking the out-of-scope table | -| PR template | Type checkbox, description, testing evidence, quality gate checklist | +| PR template | Leads with "What problem does this solve?"; then type, change, testing evidence, DCO + quality-gate checklist | **Rationale:** The highest-value contributions (hardware quirks) come from users who may not be experienced OSS contributors. Templates reduce the back-and-forth from "please add @@ -140,6 +141,32 @@ and CI-tested before merge. looking at this?" pings. Hardware quirks are fast-tracked because each one unlocks support for an entire laptop model. +### 9. PR Evaluation: Problem-First Triage + +*(Amendment, 2026-07-07.)* A pull request is treated as a **request to push a change** — +evaluated from the problem down, not the diff up. Every PR (external, dependabot, or +maintainer) is read through this ladder **before** line-by-line code review: + +1. **What problem does it solve?** No stated problem — or a solution hunting for one — is + asked "what's the problem here?" before its code is reviewed. +2. **Is that problem in scope?** Measured against the out-of-scope boundaries in + `CONTRIBUTING.md`. Out-of-scope PRs are declined with the boundary, not the code. +3. **Is it the right solution?** A real, in-scope problem can still have the wrong fix — + the bar is the simplest approach that fits the architecture and does not widen the + auth/attack surface. +4. **Is it verifiable?** Evidence (tests, a repro, `visage discover` output) plus green CI. +5. **Governance** — DCO, security-path review, merge strategy, attribution (§§3–5 above). + +**Rationale:** The other decisions here govern *how* a PR is handled (branch protection, +DCO, CI, timelines); they do not say *how it is judged*. Codifying the problem-first ladder +makes evaluation consistent and delegable — a maintainer, or an automated agent handling +routine PRs, applies the same lens, rejects/redirects early on the upper rungs (cheaper for +us, kinder and faster for the contributor), and escalates only genuine judgment calls: +scope-edge decisions, anything on the security/auth path, governance waivers, and +breaking/release-version calls. Surfaced to contributors in `CONTRIBUTING.md` +("How we evaluate a PR") and in the PR template, which now leads with +"What problem does this solve?". + --- ## Consequences