From 5bb514cd695eaea72c99e52ffb4bc4848f1eb557 Mon Sep 17 00:00:00 2001 From: Shane McCarron Date: Fri, 20 Mar 2026 15:59:07 -0500 Subject: [PATCH 1/3] =?UTF-8?q?docs(contributing):=20add=20structured=20PR?= =?UTF-8?q?=20process=20=E2=80=94=20issue-first,=20QA=20cycle,=20commit=20?= =?UTF-8?q?format?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #84 --- CONTRIBUTING.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6552369..2de6013 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,6 +84,23 @@ Language support is split between two layers: 4. Add a test case in `tests/test_pipeline.c` for integration-level fixes 5. Verify with a real open-source repo +## Commit Format + +Use conventional commits: `type(scope): description` + +| Type | When to use | +|------|-------------| +| `feat` | New feature or capability | +| `fix` | Bug fix | +| `test` | Adding or updating tests | +| `refactor` | Code change that neither fixes a bug nor adds a feature | +| `perf` | Performance improvement | +| `docs` | Documentation only | +| `style` | Formatting, whitespace (no logic change) | +| `chore` | Build scripts, CI, dependency updates | + +QA round fix commits must use the format `fix(scope): address QA round N` (e.g. `fix(pipeline): address QA round 2`). + ## Pull Request Guidelines - **C code only** — this project was rewritten from Go to pure C in v0.5.0. Go PRs will be acknowledged and potentially ported, but cannot be merged directly. @@ -91,7 +108,49 @@ Language support is split between two layers: - Include tests for new functionality - Run `scripts/test.sh` and `scripts/lint.sh` before submitting - Keep PRs focused — avoid unrelated reformatting or refactoring -- Reference the issue number in your PR description + +## Pull Request Process + +1. **Open an issue first.** Every PR must reference a tracking issue. Accepted formats: + - Closing keywords: `Fixes #N`, `Closes #N`, `Resolves #N` + - Full GitHub issue URLs: `https://github.com/owner/repo/issues/N` + - Bare issue references: `#N` (any `#` followed by a valid issue number) + - Sidebar-linked issues (via the GitHub "Development" section on the PR) +2. Describe what changed and why. Include before/after if relevant. +3. Test your changes against at least one real project (not the repo itself). +4. **Run QA review before marking ready.** Repeat this cycle at least 3 times (or until the latest report contains no confirmed critical/major issues): + + > **Docs-only or trivial PRs:** The QA round requirement only applies when the PR touches logic paths. PRs that only change docs, CI config, or repo metadata skip the check automatically. + + **Step A — Run the QA prompt.** Open a **new** Claude Code (or other AI) session using a top-tier model — **Claude Opus 4.6**, **GPT-5.3 Codex high/xhigh**, or **Gemini 3.1 Pro**. Smaller models (Haiku, Sonnet, etc.) don't produce thorough enough reviews. Paste the prompt below (fill in the placeholders). *(Prompt approach inspired by [@dpearson2699](https://github.com/dpearson2699)'s work in the [VBW project](https://github.com/yidakee/vibe-better-with-claude-code-vbw).)* + + ````text + You are a read-only QA reviewer. Do NOT modify files, make commits, or push fixes — report only. + + PR: # + Branch: + + 1. Review the commits in the PR to understand the change narrative. + 2. Read all files changed in the PR for full context. + 3. Act as a devil's advocate — find edge cases, missed regressions, and untested + paths the implementer didn't consider. + + Do NOT prescribe what to test upfront. Discover what matters by reading the code. + + Report format (use a markdown code block): + - Model used: (e.g., Claude Opus 4.6, GPT-5.3 Codex (high or xhigh), Gemini 3.1 Pro) + - What was tested + - Expected vs actual + - Severity (critical / major / minor) + - Confirmed vs hypothetical + ```` + + **Step B — Fix the findings.** Copy the QA report and paste it into your original working session (or a new session on the same branch). Tell it to fix the issues found. Each QA round's fixes must be a **separate commit** — do not amend previous commits. Use the format `fix(scope): address QA round N`. + + **Step C — Repeat.** Go back to Step A with a fresh session. The new QA round will see the fix commits from Step B and look for anything still missed. Continue until a round comes back clean or only has hypothetical/minor findings. + + **Proving your work:** Paste each round's QA report as a separate comment on the PR. Reviewers will cross-reference the reports against the fix commits in the PR history. + ## Security From 1ab2310bcf9c8ee0f8ca8bbf2526e8b74fdb7c51 Mon Sep 17 00:00:00 2001 From: Shane McCarron Date: Fri, 20 Mar 2026 18:39:39 -0500 Subject: [PATCH 2/3] =?UTF-8?q?docs(contributing):=20clarify=20QA=20report?= =?UTF-8?q?=20format=20=E2=80=94=20rendered=20markdown=20not=20fenced=20co?= =?UTF-8?q?de=20block?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- CONTRIBUTING.md | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2de6013..cecabe0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -137,19 +137,33 @@ QA round fix commits must use the format `fix(scope): address QA round N` (e.g. Do NOT prescribe what to test upfront. Discover what matters by reading the code. - Report format (use a markdown code block): - - Model used: (e.g., Claude Opus 4.6, GPT-5.3 Codex (high or xhigh), Gemini 3.1 Pro) - - What was tested - - Expected vs actual - - Severity (critical / major / minor) - - Confirmed vs hypothetical - ```` + Report format — post as **rendered markdown**, not a fenced code block. Use this structure: + + ``` + ## QA Round N — `branch-name` + + **Model used:** Claude Opus 4.6 + + ### Findings + + **[Finding N] SEVERITY: Title** + - **What was tested:** ... + - **Expected vs actual:** ... + - **Severity:** critical / major / minor / nit + - **Confirmed vs hypothetical:** ... + + --- + + **SUMMARY: N critical, N major, N minor findings.** + ``` + + > **Formatting note:** Paste the report as plain markdown text in the PR comment box — do not wrap the entire report in a fenced code block (` ``` `). GitHub renders markdown in comments; wrapping it defeats this and makes the report harder to read. **Step B — Fix the findings.** Copy the QA report and paste it into your original working session (or a new session on the same branch). Tell it to fix the issues found. Each QA round's fixes must be a **separate commit** — do not amend previous commits. Use the format `fix(scope): address QA round N`. **Step C — Repeat.** Go back to Step A with a fresh session. The new QA round will see the fix commits from Step B and look for anything still missed. Continue until a round comes back clean or only has hypothetical/minor findings. - **Proving your work:** Paste each round's QA report as a separate comment on the PR. Reviewers will cross-reference the reports against the fix commits in the PR history. + **Proving your work:** Paste each round's QA report as a separate PR comment in rendered markdown. Reviewers will cross-reference the reports against the fix commits in the PR history. ## Security From 4814864053d53f1315540aa9ca04e130ed6f7506 Mon Sep 17 00:00:00 2001 From: Shane McCarron Date: Sat, 21 Mar 2026 13:25:25 -0500 Subject: [PATCH 3/3] docs(contributing): remove fixed 3-round minimum from QA process MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stop early when a QA round is already clean — no confirmed critical or major findings means no further rounds are needed. Co-Authored-By: Claude Sonnet 4.6 --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cecabe0..24cd6f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -118,7 +118,7 @@ QA round fix commits must use the format `fix(scope): address QA round N` (e.g. - Sidebar-linked issues (via the GitHub "Development" section on the PR) 2. Describe what changed and why. Include before/after if relevant. 3. Test your changes against at least one real project (not the repo itself). -4. **Run QA review before marking ready.** Repeat this cycle at least 3 times (or until the latest report contains no confirmed critical/major issues): +4. **Run QA review before marking ready.** Run this cycle until a round comes back clean (no confirmed critical or major findings). If the first round is already clean, no further rounds are needed: > **Docs-only or trivial PRs:** The QA round requirement only applies when the PR touches logic paths. PRs that only change docs, CI config, or repo metadata skip the check automatically.