Principle: Small PRs merge faster

Large pull requests take days to review, get rubber-stamped, and are more likely to introduce bugs.

Keep PRs small and focused:

Guidelines:

• Target: < 400 lines changed (ideal: < 200)
• One logical change per PR
• If the description needs more than 3 bullet points, split the PR

How to split large changes:

1. Refactor first, feature second:

- PR 1: Refactor existing code to prepare for new feature
- PR 2: Add the new feature on clean foundation

1. Vertical slices:

- PR 1: Backend API endpoint (with tests)
- PR 2: Frontend UI that calls it (with tests)

1. Feature flags:

- Ship incomplete features behind flags
- Each PR adds a piece, all hidden from users
- Final PR: enable the flag

1. Mechanical changes separately:

- PR 1: Rename across codebase (easy to review)
- PR 2: Logic changes (needs careful review)

The math:

• 100-line PR: reviewed in 15 min, merged same day
• 1000-line PR: reviewed in 2 hours (spread over days), merged in 3-5 days
• Bug rate correlates with PR size, not linearly but exponentially

The best PR is one a reviewer can hold entirely in their head.

Research (Microsoft, Google) shows defect density increases with change size. Small PRs get more thorough reviews and ship faster.

Team development workflow and code review practices