Skip to content

Commit 5bb514c

Browse files
committed
docs(contributing): add structured PR process — issue-first, QA cycle, commit format
Closes DeusData#84
1 parent de42777 commit 5bb514c

1 file changed

Lines changed: 60 additions & 1 deletion

File tree

‎CONTRIBUTING.md‎

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,14 +84,73 @@ Language support is split between two layers:
8484
4. Add a test case in `tests/test_pipeline.c` for integration-level fixes
8585
5. Verify with a real open-source repo
8686

87+
## Commit Format
88+
89+
Use conventional commits: `type(scope): description`
90+
91+
| Type | When to use |
92+
|------|-------------|
93+
| `feat` | New feature or capability |
94+
| `fix` | Bug fix |
95+
| `test` | Adding or updating tests |
96+
| `refactor` | Code change that neither fixes a bug nor adds a feature |
97+
| `perf` | Performance improvement |
98+
| `docs` | Documentation only |
99+
| `style` | Formatting, whitespace (no logic change) |
100+
| `chore` | Build scripts, CI, dependency updates |
101+
102+
QA round fix commits must use the format `fix(scope): address QA round N` (e.g. `fix(pipeline): address QA round 2`).
103+
87104
## Pull Request Guidelines
88105

89106
- **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.
90107
- One logical change per PR — don't bundle unrelated features
91108
- Include tests for new functionality
92109
- Run `scripts/test.sh` and `scripts/lint.sh` before submitting
93110
- Keep PRs focused — avoid unrelated reformatting or refactoring
94-
- Reference the issue number in your PR description
111+
112+
## Pull Request Process
113+
114+
1. **Open an issue first.** Every PR must reference a tracking issue. Accepted formats:
115+
- Closing keywords: `Fixes #N`, `Closes #N`, `Resolves #N`
116+
- Full GitHub issue URLs: `https://github.com/owner/repo/issues/N`
117+
- Bare issue references: `#N` (any `#` followed by a valid issue number)
118+
- Sidebar-linked issues (via the GitHub "Development" section on the PR)
119+
2. Describe what changed and why. Include before/after if relevant.
120+
3. Test your changes against at least one real project (not the repo itself).
121+
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):
122+
123+
> **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.
124+
125+
**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).)*
126+
127+
````text
128+
You are a read-only QA reviewer. Do NOT modify files, make commits, or push fixes — report only.
129+
130+
PR: #<number>
131+
Branch: <branch-name>
132+
133+
1. Review the commits in the PR to understand the change narrative.
134+
2. Read all files changed in the PR for full context.
135+
3. Act as a devil's advocate — find edge cases, missed regressions, and untested
136+
paths the implementer didn't consider.
137+
138+
Do NOT prescribe what to test upfront. Discover what matters by reading the code.
139+
140+
Report format (use a markdown code block):
141+
- Model used: (e.g., Claude Opus 4.6, GPT-5.3 Codex (high or xhigh), Gemini 3.1 Pro)
142+
- What was tested
143+
- Expected vs actual
144+
- Severity (critical / major / minor)
145+
- Confirmed vs hypothetical
146+
````
147+
148+
**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`.
149+
150+
**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.
151+
152+
**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.
153+
95154

96155
## Security
97156

0 commit comments

Comments
 (0)