Pull Request Conventions

What it is

The convention for how w3dev pull requests are structured and reviewed: what a PR body must contain, how large changes get split, how branches are named, and what's never allowed regardless of urgency.

Why we adopted this

• Reviewable by default. A Manual Testing Guide tells a reviewer exactly how to verify the change themselves, instead of trusting the description or re-deriving a test plan from the diff.
• Small PRs, fast reviews. A focused, stacked PR is reviewable in minutes; a sprawling one either gets rubber-stamped or stalls — neither outcome is good.
• Predictable history. Consistent branch naming and conventional commit-style PR titles keep git log and the PR list scannable, and feed the same tooling that reads Conventional Commits (see specs/conventional-commits.md).
• Hooks exist for a reason. Bypassing commit hooks trades a short-term speed-up for an unverified commit landing in history — not a trade w3dev makes.

w3dev-specific notes

• Manual Testing Guide required. Every PR body includes a section titled "Manual Testing Guide" — concrete steps a reviewer can follow to verify the change locally or in a sandbox (see specs/sandbox.md). "Tested locally" with no steps does not satisfy this.
• Split large changes. A change that touches multiple concerns is split into focused, stacked PRs — each independently reviewable and landing in sequence — rather than shipped as one large PR. If a change can't be reviewed in one sitting, it's a signal to split it.
• Branch naming: <type>/<short-description>, using the same type vocabulary as Conventional Commits (feat, fix, chore, docs, refactor, test, ci) — e.g. fix/empty-request-body.
• PR title: follows Conventional Commit style (type(scope): description), since squash-merge titles become the permanent commit message on main.
• Never bypass commit hooks. --no-verify (or any other hook-skip) is forbidden. If a hook fails, fix the underlying issue or fix the hook — don't skip it.

Links

• Related: specs/conventional-commits.md, specs/sandbox.md