Chapter 3: Writing PR Descriptions That Get Reviewed Faster

Why this matters

A PR description is the reviewer's first, and sometimes only, source of context before diving into a diff — a well-written one can save a reviewer significant time (and produce a faster, better-targeted review) while a missing or thin one forces every reviewer to reconstruct context from scratch, or worse, review without ever fully understanding the change's actual intent.

What a good PR description actually needs

[BEGINNER] A useful PR description answers, without requiring the reviewer to ask:

1. What problem does this solve, and why does it need solving now? (the motivation)
2. What approach was taken, and why this approach over alternatives? (especially if a non-obvious choice was made)
3. What's explicitly out of scope? (preventing "why didn't you also fix X" comments about something deliberately excluded)
4. How was this tested/verified? (giving the reviewer confidence beyond just reading the diff)

## What
Adds rate limiting to the public API to prevent abuse after INC-4521,
where a single misbehaving client made 50,000 requests/minute and
degraded service for all other clients.

## Approach
Using a token bucket algorithm (via the `rate-limiter-flexible` library)
rather than a simple fixed-window counter, since token bucket handles
bursty-but-legitimate traffic more gracefully (a fixed window can reject
a legitimate burst right at a window boundary even when average request
rate is well within limits).

## Out of scope
This PR rate-limits by IP address only. Per-API-key rate limiting
(for authenticated requests) is tracked separately in TICKET-892.

## Testing
- Added unit tests for the rate limiter's core logic (see `rateLimiter.test.ts`)
- Manually verified via load testing script (`scripts/load-test.js`) that
  50,000 req/min from one IP is now correctly throttled to the configured limit

Why "what" alone isn't enough

[SENIOR INSIGHT] A PR description that only states what changed (often barely more informative than the diff itself, or a restatement of the PR title) misses the description's actual value — directly the same principle as the Coding Standards book's Chapters 4 and 8: the diff already shows what changed; the description's job is to convey what the diff cannot: the motivation, the alternatives considered and rejected, and the deliberate scope boundary. A reviewer who understands why a particular approach was chosen can evaluate whether that reasoning holds up — a reviewer who only sees what changed can only check the code in isolation, missing an entire category of feedback ("have you considered X approach instead?") that requires knowing what was already considered.

Linking to context instead of duplicating it

[IN PRACTICE] Rather than re-explaining a requirement or a prior discussion's outcome from scratch in every PR description, link directly to the source (a ticket, a design doc, a Slack thread, an incident writeup) — this keeps the description concise while giving a reviewer who wants deeper context an immediate path to it, without asking the author to duplicate and maintain that context in two places that can drift out of sync.

## What
Implements the caching strategy agreed in [design doc: Checkout Performance
Improvements](link). Addresses the P1 latency issue tracked in TICKET-773.

Screenshots and recordings for visual changes

[BEGINNER] For any UI-affecting change, a before/after screenshot (or a short screen recording for interactive behavior) lets a reviewer verify the visual/behavioral result without needing to pull the branch and run it locally — a small additional authoring effort that often saves significantly more reviewer time than it costs, especially for a reviewer working asynchronously (Chapter 10) who might not have easy access to run the change themselves right away.

Common mistakes

1. Writing a PR description that only restates the title or the diff's mechanical contents, missing the actual value a description provides: the motivation and reasoning a diff alone can't convey.
2. Leaving scope boundaries implicit, inviting "why didn't this also handle X" comments about something the author deliberately, reasonably excluded — stating scope explicitly prevents this category of unproductive back-and-forth entirely.
3. Duplicating extensive context from a ticket or design doc directly into the PR description rather than linking to it, creating two copies of the same information that can drift out of sync over time.
4. Skipping screenshots/recordings for UI changes, forcing every reviewer to pull the branch and run it locally just to verify a visual result that a screenshot would have shown instantly.

Checklist: writing an effective PR description

1. State the problem/motivation explicitly — don't assume the reviewer already has full context, even for a ticket they might have seen before.
2. Explain the chosen approach and why, especially if it's non-obvious or if a reasonable alternative was considered and rejected.
3. State what's explicitly out of scope, to prevent unproductive scope-creep comments about deliberate exclusions.
4. Describe how the change was tested/verified, giving the reviewer confidence beyond what the diff alone shows.
5. Link to relevant context (tickets, design docs) rather than duplicating it, and include screenshots/recordings for any UI-affecting change.

Discussion / interview questions

1. "What should a good PR description include, beyond a summary of the code changes?" Strong answer: The problem/motivation, the chosen approach and why (especially if non-obvious), what's explicitly out of scope, and how the change was tested — information the diff itself can't convey, directly paralleling the "explain why, not what" principle from commit messages and comments.

2. "Why should a PR description state what's explicitly out of scope?" Strong answer: Prevents reviewers from raising "why didn't you also fix X" comments about something the author deliberately, reasonably excluded — making the scope boundary explicit heads off this category of unproductive, avoidable back-and-forth before it starts.

3. "Should a PR description duplicate the full context from a linked ticket or design doc?" Strong answer: No — link to the source instead of duplicating it, keeping the description concise while still giving an interested reviewer an immediate path to deeper context, and avoiding two copies of the same information that can silently drift out of sync over time.

4. "Why are screenshots or recordings valuable for a PR that changes UI behavior?" Strong answer: They let a reviewer verify the visual/behavioral result immediately, without needing to pull the branch and run it locally — a small authoring cost that often saves significantly more reviewer time, especially valuable for asynchronous reviewers who might not run the change themselves right away.

Chapter summary / cheat sheet

• A good PR description answers: what problem, what approach and why, what's out of scope, and how it was tested — information the diff alone can't convey.
• Explicitly stating scope boundaries prevents unproductive "why didn't you also do X" review comments.
• Link to tickets/design docs rather than duplicating their context, to avoid information drifting out of sync across two copies.
• Include screenshots/recordings for UI changes — a small authoring cost that saves meaningful reviewer time, especially for asynchronous review.

---