PR Description Structure
Summary, root cause, test notes, UI evidence, and issue linking
PR description essentials
- Formula: what changed + root cause + solution + test coverage + issue reference
- Summary: problem + why + approach — 2–4 sentences, not a file list
- Test notes: what IS tested + what new tests were added — never just "logic is straightforward"
- UI changes: before/after screenshots or screen recording — always
- Auto-close issues: use "Fixes #N", "Closes #N", or "Resolves #N" in the description
Question 0 of 5
Which pull request description is written most effectively?
What changed + root cause + solution + test coverage + issue reference. PR description anatomy:
- What: "Fixes the session timeout bug that logged users out during file uploads" — the user-visible problem
- Issue link: "Fixes #892" — closes the issue automatically on merge
- Root cause: "upload endpoint did not extend the session token while streaming" — WHY it happened
- Solution: "call refreshSession() every 60 seconds during active streams" — HOW it was fixed
- Test coverage: "integration test covering uploads > 5 minutes" — reviewer knows what's verified
What should a PR description "Summary" section answer?
Problem + why + approach — 2–4 sentences. Summary section formula:
- Problem: "Users on slow connections were being logged out during large file uploads"
- Why: "This caused data loss and support escalations from 3 enterprise customers"
- Approach: "Rather than extending the global session timeout (which would be a security regression), we refresh the session token only during active upload streams"
- Not a list of files changed (that's what the diff is for)
- Not a full spec (the description should be scannable)
- Not just a ticket number ("resolves JIRA-1234" with no context)
A PR description contains: "Note: I intentionally skipped adding unit tests here because the logic is straightforward." What is wrong with this statement?
"Straightforward" is subjective and not a testing justification. How to write a testing note correctly:
- ❌ "I skipped unit tests because the logic is straightforward"
- ✅ "Not adding unit tests: this change only modifies the call site, not the logic — the session refresh function itself has 94% unit test coverage in auth/session_test.go. Adding an integration test covering uploads > 5 min."
- What test coverage exists (file location if helpful)
- What new tests were added
- If tests were intentionally skipped, the specific reason — not "straightforward" but "this is a thin pass-through, the actual logic is already tested in X"
Which section should every PR description include when the change has UI impact?
Before/after screenshots or screen recording. Why UI evidence matters in PRs:
- Reviewers can verify the implementation matches the design without running the code locally
- Catches visual regressions that code review alone misses
- Speeds up review — "looks right" is a faster decision when you can see it
- Creates a historical record of what the UI looked like before the change
- New feature: screenshot of the finished state
- Bug fix: before screenshot showing the bug + after screenshot showing it's fixed
- Animation/transition: screen recording (GIF or MP4)
- Responsive changes: screenshots at desktop, tablet, and mobile widths
What is the correct format for linking a PR to a GitHub issue so the issue closes automatically when the PR merges?
Fixes #N, Closes #N, or Resolves #N — the exact keyword triggers auto-close on merge. GitHub auto-close keywords:
- ✅ Closes #N, Close #N, Closed #N
- ✅ Fixes #N, Fix #N, Fixed #N
- ✅ Resolves #N, Resolve #N, Resolved #N