Part 4 · 2 chapters · ~12 min

PR Size, Stacking and Descriptions

Why small PRs get better reviews, ways to split work (migrations first, refactor then behaviour, flags), stacked pull requests and tools, writing descriptions that explain why, what and how it was tested, and screenshots and previews for UI.

8

Size and stacking

The single most effective thing an author can do for review quality is make the change smaller.

PR SIZE AND REVIEW QUALITY
how review behaviour tends to change with diff size (shape, not data)
under 100 linescareful review, fast merge100-400 linesgood review if focused400-1,000 linesskimming startsover 1,000 lines"LGTM"
swipe the figure sideways, or tap expand for full screen
1/4
small
Small PRs get read carefully and merged quickly. Studies of review (including SmartBear's at Cisco) found reviewers find defects best in a few hundred lines at a time.
small diffs get real attentiona few hundred lines at a time
9

A description that does the work

code
## Why
Clearance letters currently require a support ticket (249/month). This adds self-serve generation for
fully repaid term loans (part 1 of 3; email and history come in follow-ups).

## What
- POST /loans/:id/clearance-letter: checks settled balance, generates the PDF, returns a signed URL
- Letter state machine: requested → generated | refused (with reason)
- Migration: letters table (additive, no backfill)

## How I tested
- unit: eligibility rules incl. 1-kobo balances and unsettled repayments
- integration: Testcontainers Postgres, idempotent retries (same key → same letter)
- manual: preview env, two test borrowers (screenshots below)

## Risks / rollout
Behind flag `self_serve_letters` (staff only first). Signing service load: +~2 req/s at peak.