Large pull requests

How to review a 20,000-line pull request

Huge PRs get rubber-stamped. A practical approach to reviewing very large pull requests by concern, in chapters, with the decisions shown on the lines.

Nobody reviews a 20,000-line pull request. They scroll, check that CI is green, leave a comment on something small, and approve. Then the incident review finds the decision that mattered on page forty.

Split by concern, not by file

A large branch is usually several changes stacked together: a new data model, the code that writes it, the UI that shows it, a migration. Reviewing it file by file mixes all of them on every screen.

Review it in chapters, one concern each:

1. Agree the chapters first. Usually three to five.
2. Review chapter one completely before looking at chapter two.
3. Let what you learned in one chapter shape the next.

Inside each chapter, find the decisions

In each chapter there are only a few places where something was chosen. Those deserve your full attention. The rest is consequence, and a skim is enough for it.

Ask the author, or the agent, for:

• the entry point, from the user's side
• the two or three lines where behaviour actually changed
• what the tests prove, and what they do not

How deck handles a big review

deck was shaped by exactly this case. Ask your agent to review the branch with deck, and it proposes the chapters first and asks before it starts. Each chapter opens as its own deck: a map of the branch, then the changes one claim at a time, with the code lit beside each sentence. A change shows as the old lines going and the new lines arriving.

When something looks wrong you comment on the line. Your review of chapter one goes back to the agent before it writes chapter two, so the review gets sharper as it goes instead of more tired.

If you are the author

Make the reviewer's job possible. Split the branch, or at least say what the chapters are. Put the risky decisions first. Say plainly what you could not test. A reviewer who trusts your map will read the parts that matter.