Keeping it 100

We’ve written in the past about how we encourage pull requests with less than 100 additions. In this blog, we take a closer look at where the guideline comes from and how it works in practice.

Origins

It’s worth noting that managing the line count in a pull request itself is not the goal, but more of a means to an end.

We are mainly concerned with the number of concepts.

While a pull request should have enough context to be understandable, we have found that limiting the overall number of concepts has several benefits:

Reduced risk of getting blocked

The more things going on in a pull request, the greater the likelihood of getting blocked.

For example, a pull request containing a refactoring, a novel pattern introduction, and a new feature implementation all at once risks getting stuck should questions arise around any of those.

By splitting out the refactoring into a new pull request it can be submitted, reviewed, and merged separately. Similarly, on a different pull request the new pattern could be discussed.

Safer deployments

In our setup merging to the main branch triggers an automatic deployment to production.

Limiting the amount of code that gets released at one time reduces the number of things that can go wrong and ensures that a targeted revert is easy to do should it become necessary.

Better review quality

Reviewers’ time and bandwidth are limited, and the more they need to take in and give feedback on at a time, the less able they will be to do so in a meaningful way.

This might lead to missing key details or even giving the review a pass and “doing it later.”

Early course correction

Reviewing a pull request containing a fully completed feature and noticing a better path that could have been taken several commits earlier is a painful situation to be in for all.

Sharing (even unfinished) results early helps detect problems or alternate solutions and build consensus early on.

Review speed

A tightly scoped pull request with less code to read helps reviewers get through it more quickly and makes it more appealing to pick up in the first place.

Relying on constraints

Working in this way requires discipline and being mindful of how and when to share code with the team.

The <100 additions constraint works as a guide and reminder, that should be just enough to make you stop and think.

100 has shown itself to be the sweet spot for checking whether there might be an issue or better alternative to uncover.

That’s not to say there aren’t times where a larger pull request is warranted (and it is equally possible to stuff a pull request with multiple concepts in few lines of code).

This is also why we ultimately encourage the behavior, rather than having it as a strict rule.

We subtly incentivize this behavior by having our review bot notify reviewers for small pull requests in a dedicated chat channel:

Larger pull requests will have the mentions omitted and rely on being found through the GitHub inbox.

It doesn’t mean you won’t get reviewed if you have more than 100 additions but sets the expectation that while a <100 pull request will get reviewed within hours (even minutes at times), it might take a little longer for anything bigger.

Staying on course

As can be the case with any metric, people may lose sight of the intent and overly focus on the metric itself.

A few common indicators of this are as follows:

Problem: Artificially splitting already written code to keep under the 100 addition mark in a way that omits the required context for reviewing (an example could be submitting just the migration of an already written model).

Solution: Consider revisiting development style, f.ex using the top-down approach or progressive enhancement to avoid the problem in the first place, or diverge from the guideline when it makes sense.

Problem: Committing inappropriate workarounds, such as removing line breaks that were helping readability in order to stay within the constraint.

Solution: Code quality and readability should always take priority over any guideline. Just as with our 120 character line length limit, the intent is to put enough pressure on the code to come up with better code, not to make compromises to hit a numerical target.

Problem: Chain of unreviewed pull requests depending on each other piling up.

Solution: Both submitters and reviewers have a responsibility to ensure a tight review loop. Submitters sharing their work early in a well-presented manner helps expedite the work of reviewers, who on their end commit to reviewing in a timely manner.

However, it is a balancing act to limit interruption while also unblocking others, so should one find themselves in a situation of starting a third dependent pull request, consider manually pinging the team for help.

While it does require a particular mindset and discipline to follow, the simple presence of this constraint has led to a noticeable improvement in review turnaround, quality, and several innovations in how we work.