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