Most developers, given a choice, would rather review a smaller pull request. It's valuable to foster team agreement about what constitutes an optimally sized PR.

While smaller PRs are generally better, there can be trade-offs:

Advantages of smaller PRs

• More people are likely to review them.

• Reviewers are more likely to fully comprehend the changes.

• More developers can work on the same feature in unison.

• They tend to be merged quickly.

Disadvantages

• Small PRs for changes affecting multiple interdependent parts of the codebase

  • can lead to merge conflicts and generally more admin maintaining git branches

  • and create a greater need for communication between developers and greater cost for failure to communicate.

• For new endpoints: test data can be harder to create as there’s no public way of creating it.

How to measure PR size?

Merge with the main branch,

git fetch --all && git merge origin

get diff stats with the main branch

git diff --stat origin/main your-branch

and add the totals for insertions and deletions.

What to aim for for?

Maybe we can somehow measure the time takes to review?

Optimal pull request size - Small Business Programming

Simpler suggestion: we calibrate what PR-size adjectives mean and then agree on what to aim for.

• tiny < 15 lines

• small: 16-99 lines

• medium: 100 - 399 lines

• big: 400-749 lines

• huge: > 750 lines

Aim for tiny, small or medium?

How big is considered problematic?

To start a discussion, let's say a problematic PR exceeds 750 lines.

This may seem a lot, but depending on the programming language, tools and frameworks used, every change could include some necessary boilerplate.

For example, to add a reasonable chunk of a product feature to Django API code, integration tests comprise 50 or more lines, and one PR could include several of these. OpenAPI documentation for APIs could add another 150 lines. This would mean the cut-off point is 400 lines of business logic, which is still a lot.

Is big always “bad”?

While it would be nice if all PRs were small, this isn’t always practical. There are legitimate reasons for larger PRs.

• The whole thing needs to be tested as a whole.

• The system being extended is tightly coupled.

What extra measures to take with huge PRs?

I think it's a good idea that if engineers open a huge PR, they are responsible for organizing and advertising a short meeting to walk through and explain the code to interested parties.

Conclusion

In conclusion, while smaller pull requests are generally more manageable and facilitate quicker, more thorough reviews, they are not without their drawbacks. The ideal PR size is context-dependent, balancing the need for clarity and comprehensibility with the practical realities of the codebase and project requirements.

Establishing team-wide guidelines on PR size, such as categorizing them by line count, can help streamline the review process. However, it's important to remain flexible, acknowledging that larger PRs may be necessary for certain tasks.