Skip to content
Back to Quality Assurance

PR Size

Keep pull requests small and focused so they can be reviewed thoroughly in minutes, not skimmed in hours.

Why

A 1000-line PR cannot be reviewed — the reviewer skims it, clicks approve, and bugs ship. Research from Google and Microsoft shows that review effectiveness drops sharply above 400 lines: the reviewer's ability to find defects declines, their fatigue increases, and the review becomes a rubber stamp. Small PRs, by contrast, can be reviewed thoroughly in 15 minutes, the reviewer has the context to find real bugs, and the feedback is specific and actionable. Small PRs also fail faster — a 100-line PR that breaks the build is fixed in 10 minutes, while a 1000-line PR that breaks the build takes 2 hours to debug because the breakage could be anywhere. The discipline of small PRs also forces the author to think in incremental changes, which produces better-designed code. The rule is simple: if the PR is too big to review thoroughly, it is too big to merge.

When

For every pull request — if the PR exceeds 400 lines, split it before requesting review.

How

1. Target < 400 lines per PR
   - 200 lines is ideal — reviewable in 15 minutes
   - 400 lines is the upper limit — reviewable in 30 minutes
   - 1000+ lines cannot be reviewed thoroughly — split it

2. One PR per change
   - One feature, one bug fix, one refactor — not a mix
   - A PR that does three things is three PRs
   - If the changes are unrelated, they should be separate PRs

3. Split large changes into a stack of PRs
   - PR 1: add the data model and migration
   - PR 2: add the service layer (depends on PR 1)
   - PR 3: add the API endpoint (depends on PR 2)
   - PR 4: add the UI (depends on PR 3)
   - Each PR is small and reviewable independently

4. Use feature flags for incomplete features
   - Merge the infrastructure behind a flag, then enable in a later PR
   - This lets you merge small PRs without exposing the feature

5. Make the PR easy to review
   - Write a clear description: what, why, how, testing
   - Add screenshots for UI changes
   - Link the issue or design doc
   - Self-review the diff before requesting review

Example

// Bad: a 1500-line PR that does everything
// feat: add user registration
// - database migration (200 lines)
// - user model (150 lines)
// - email service (300 lines)
// - registration API (200 lines)
// - welcome email template (150 lines)
// - registration form UI (300 lines)
// - form validation (200 lines)
// Total: 1500 lines — cannot be reviewed thoroughly

// Good: split into a stack of small PRs
// PR 1: feat: add user model and migration (150 lines)
//   - db/migrations/001_add_users.sql
//   - src/models/user.ts
//   - tests/models/user.test.ts

// PR 2: feat: add email service (200 lines) [depends on PR 1]
//   - src/services/email.ts
//   - src/templates/welcome.ts
//   - tests/services/email.test.ts

// PR 3: feat: add registration API (200 lines) [depends on PR 2]
//   - src/api/register.ts
//   - src/api/register.test.ts
//   - validates input, creates user, sends email

// PR 4: feat: add registration form (250 lines) [depends on PR 3]
//   - src/components/RegisterForm.tsx
//   - src/components/RegisterForm.test.tsx
//   - src/pages/register.tsx

// PR description template:
"""
## What
Add user registration with email verification.

## Why
Users cannot create accounts — this is the top user request.

## How
1. Add user model and migration (PR 1)
2. Add email service for welcome email (PR 2)
3. Add registration API endpoint (PR 3)
4. Add registration form UI (PR 4)

## Testing
- Unit tests for model, service, API, and form
- Integration test for the full flow
- Manually tested: register → receive email → verify

## Checklist
- [x] Tests added
- [x] No breaking changes
- [x] Self-reviewed the diff
"""

Common Problems

  • ⚠Opening a 1000-line PR because "the feature is one thing" — the reviewer skims it, approves it, and a bug in the email service ships because nobody read that part.
  • ⚠Mixing a bug fix with a refactor in the same PR — the reviewer cannot tell which changes are the fix and which are the refactor, and if the refactor causes a regression, the fix is blamed.
  • ⚠Splitting PRs but making each PR depend on the previous unmerged PR — the reviewer cannot run the code without merging all PRs, and the review is blocked.
  • ⚠Writing a one-line PR description ("fix bug") — the reviewer has no context, must read the diff to understand the change, and the review takes twice as long.

Best Practices

  • ✓Target < 400 lines per PR (200 is ideal) — research shows review effectiveness drops sharply above 400 lines, and small PRs are reviewed thoroughly in 15 minutes.
  • ✓One PR per change — a PR that does a bug fix and a refactor and a feature is three PRs, and mixing them makes the review harder and the blame harder to assign if something breaks.
  • ✓Write a clear PR description (what, why, how, testing) — the reviewer needs context to review effectively, and a good description halves the review time.
  • ✓Self-review the diff before requesting review — you will catch typos, debug logs, and obvious issues, and the reviewer's time is spent on the subtle problems you missed.