Skip to content

docs: document structured PR/QA review process in CONTRIBUTING.md #84

@halindrome

Description

@halindrome

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:

  1. Commit format guidance — document the conventional commit convention (type(scope): description) already in use across the project history
  2. Issue-first requirement — every PR must reference a tracking issue; document accepted linking formats
  3. Pull Request Process section — numbered submission checklist (open issue → describe changes → test against real project → QA review)
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions