a love letter to smaller pull requests

A Love Letter to Small PRs

Marc Simard
June 28, 2023

At Setori, we love small pull requests (or merge requests, for our GitLab friends). As a startup, we prize iteration speed - land code, get feedback, improve. We decided to take this week’s newsletter to praise their benefits! We’ll also discuss what _is_ a small PR (hint: it’s not just lines of code) and steps you can take today to move your team towards shipping smaller PRs. 

The benefits of small PRs

1. Easier to Review

Shorter PRs are generally easier to review than larger ones. The reviewer can understand the changes more thoroughly, which often leads to higher-quality reviews. This improves the chance of spotting bugs or issues before they get merged into the codebase.

2. Faster to Review

Smaller changes can be reviewed more quickly than larger ones. This reduces the time between when code is written and when it is merged, leading to quicker iterations and a more agile development process.

3. Easier to Merge

Shorter PRs are less likely to result in merge conflicts, which can be time-consuming and difficult to resolve. This is especially true in teams with many members who are all making changes to the codebase.

4. Less Risky

Shorter PRs introduce fewer changes to the codebase at once, reducing the risk of unintended side effects. In the case of a problem, it's easier to identify the cause and to roll back if necessary.

5. Clearer Ownership

In the same vein, encouraging short PRs often leads to the development of features and fixes that adhere to the single responsibility principle. This means each PR makes one clear change, making it easier to understand what's changing and why.

6. Earlier Feedback

Shorter PRs foster a rapid feedback loop. If a developer's approach is misaligned, feedback can be received swiftly with a small, focused PR, preventing substantial time and effort on potentially misguided directions.

7. More Learning

For new members in the team, it's easier to learn from short, focused PRs that make one clear change. Large PRs can be overwhelming and harder to learn from.

8. Greater Positive Momentum

Short PRs naturally encourage more frequent commits, which can create a positive feedback loop. The act of completing tasks and submitting changes often gives a sense of accomplishment and progress. This psychological boost can increase motivation, promote productivity, and build momentum within the team, enhancing overall development flow and team morale.

What is Considered Small? 

The ideal size of a Pull Request (PR) can depend on various factors such as the team's preference, the complexity of the project, and the nature of the task at hand. However, as a general guideline, many developers and teams aim for PRs that can be thoroughly reviewed within 30 minutes to an hour.

In terms of lines of code, this might typically translate to PRs containing around 200-400 lines of changes. But remember, this isn't a hard and fast rule and the complexity of the code matters as much as, if not more than, the number of lines.

Sometimes, even a PR with 10-15 lines of code can introduce significant changes, while a PR with hundreds of lines could just be simple refactoring. Therefore, it's crucial to think of PR size in terms of cognitive load for the reviewer rather than just lines of code.

In essence, the ideal PR should be as small as possible while still providing a meaningful, coherent change. It should be self-contained and understandable to reviewers, enabling them to provide meaningful feedback.

Moving Towards Smaller Pull Requests

Implementing the habit of creating smaller Pull Requests (PRs) requires a conscious shift in the team's workflow and some good practices. Here are a few strategies your team can use to start writing smaller PRs:

Break Down Tasks

Try to decompose large tasks into smaller, manageable subtasks. Each of these should ideally result in a functional piece of code that can be committed independently. This helps in making sure that each PR addresses a single concern.

Use Feature Toggles

Feature toggles or flags can allow you to merge small pieces of a larger feature into the main codebase without affecting the end-users until the entire feature is ready.

Start with Tests

If you're following Test-Driven Development (TDD), you can write a test first, then write the code to make that test pass. Each test and corresponding code can become a separate PR.

Leverage Pull Request Templates

Use pull request templates that encourage small changes. These can serve as a reminder for the team to keep their PRs small and focused.

Start a Setori Mission

While your team might theoretically onboard to ship smaller PRs, sometimes a bit of gamification can go a long way in achieving your goals. We’ve built Setori Missions to help your team improve metrics like PR size - let us know if you want to try it out! 

As always, let me know if I can be helpful (marc@setori.ai).

Good luck, have fun, and ship smaller PRs! 😀

Happy shipping,