-
Notifications
You must be signed in to change notification settings - Fork 94
Description
Background
PR #72 (fix WAL journal mode during bulk write) received the following feedback from the maintainer on merge:
"Excellent work — this is one of the best-structured PRs we've received. The fix is minimal,
the rationale is clearly documented, and the 3-round self-QA with fixes applied after each
round shows real engineering discipline."
That PR used a specific contributor workflow:
- Each QA round was run in a fresh AI session using a top-tier model (Claude Opus 4.6)
- Findings were addressed in a separate commit per round (
fix(scope): address QA round N) - Each round's QA report was posted as a PR comment so reviewers could cross-reference fixes against findings
Contributors would benefit from clear guidance on how to structure PRs and approach quality control before submission — both to set expectations and to help contributors deliver well-validated work from the start.
Proposal
Add the following to CONTRIBUTING.md:
- Commit format guidance — document the conventional commit convention (
type(scope): description) already in use across the project history - Issue-first requirement — every PR must reference a tracking issue; document accepted linking formats
- Pull Request Process section — numbered submission checklist (open issue → describe changes → test against real project → QA review)
- QA Review Process section — Step A/B/C cycle with a reusable QA prompt template, minimum 3 rounds for logic-touching PRs, docs-only exemption, and the "prove your work" requirement (paste each round's report as a PR comment)
Goal
Make the PR #72 workflow an explicit, documented standard so future contributors have a clear path to well-structured, high-quality PRs.