Engineering Small PRs

Small PRs are easier to review thoroughly, safer to merge, easier to roll back, and less likely to waste work if the direction changes. "Small" means conceptually focused and self-contained, not merely a low line count.

Adapted from Google Engineering Practices Documentation, especially "Small CLs." Source: https://google.github.io/eng-practices/review/developer/small-cls.html. License: CC-BY 3.0.

Definition of a Good Small PR

A good PR:

• Makes one self-contained change.
• Includes the tests needed to validate that change.
• Leaves the system working after merge.
• Gives reviewers enough context in the PR, description, existing code, or earlier reviewed PRs.
• Is not so tiny that the behavior cannot be understood. A new API usually needs at least one usage in the same PR.
• Separates large refactors from behavior changes unless the cleanup is very local.

Reviewers may reasonably reject a PR solely because it is too large to review well.