PR Checklist Writing
Checklist purpose, actionable items, optimal length, content, and conditional items
PR checklist essentials
- Purpose: pre-submission self-review — catch missed steps before requesting review
- Actionable items: specific + binary (pass/fail) + includes the command to run
- Length: 5–10 items max — checkbox fatigue makes longer checklists counterproductive
- Standard items: tests pass + no debug statements + CHANGELOG + screenshots + accessibility
- Conditional items: use "N/A" for types of changes where the item doesn't apply
Question 0 of 5
What is the main purpose of a PR checklist in a GitHub PR template?
Pre-submission self-review — catch missed steps before reviewers see it. What a good PR checklist prevents:
- ❌ Reviewer comment: "Did you run the tests?" → ✅ Checklist: "[ ] Tests pass locally"
- ❌ Reviewer comment: "No changelog entry?" → ✅ Checklist: "[ ] CHANGELOG.md updated"
- ❌ Reviewer comment: "What does this look like on mobile?" → ✅ Checklist: "[ ] Tested on mobile viewport"
Which PR checklist item is most actionable?
Specific + includes the command to run + verifiable. Actionable checklist criteria:
- ✅ "All new and existing tests pass" — specific assertion
- ✅ "(run: npm test or pytest -x)" — the author knows exactly what to do
- ✅ Pass/fail is binary — either tests pass or they don't
- A ("Code is good") — what does "good" mean? Unverifiable
- B ("I reviewed my own code") — this is so vague it can always be checked without doing anything
- D ("best practices") — subjective, unchecked against any standard
A team's PR template has 25 checklist items. What is the most likely consequence?
Checkbox fatigue — authors rubber-stamp without reading. Optimal PR checklist length:
- 5–10 items maximum — each one specific and actionable
- More than 10 items → authors start speed-clicking without reading
- Items become a ritual, not a genuine check
- Remove items that CI already enforces (lint, type check, test pass) — if CI blocks merge, the checkbox is redundant
- Move rare items to a comment template ("For database migrations: [ ] Down migration tested")
- Items that require judgement ("[ ] Code is readable") should be in the code review, not the checklist
Which items are most appropriate for a standard PR checklist for a web application team?
Tests + cleanup + changelog + UI evidence + accessibility. Standard web app PR checklist:
- ✅ All tests pass locally
- ✅ No debug statements / console.log / TODO (unless tracked)
- ✅ CHANGELOG.md updated (if applicable)
- ✅ Screenshots attached (if UI change)
- ✅ Tested in major browsers / responsive (if UI change)
- ✅ Accessibility: no new WCAG violations (if UI change)
- ✅ Linked issue or ticket number included
When should a checklist item include "N/A — not applicable" as an option?
Conditional items: mark as "N/A" for the change types where they don't apply. Conditional checklist patterns:
- "[ ] Screenshots attached (for UI changes) — N/A for this PR (backend-only change)"
- "[ ] Database migration includes rollback — N/A for this PR (no schema change)"
- "[ ] API documentation updated — N/A for this PR (no API changes)"
- Prevents the "this doesn't apply but I have to check it" dilemma
- Keeps the checklist honest — a checked box means "done", not "skipped"
- Reviewers can see what was intentionally not done vs. what was forgotten