Pull-Requests are a mechanism to notify others about changes to a branch that you want to merge. It is often used in combination with trunk-based development, where you let your teammates know that your changes are ready to be merged into the trunk. Open-source software (OSS) uses this mechanism too because the requester usually does not have permission to merge directly.
But Pull-Requests are more than a notification mechanism. They can raise awareness in the team about some specific feature, spread knowledge between teammates, and even exercise control over what is merged. It is a mechanism for collaboration.
However, to make this collaboration work, you need someone to review your Pull-Requests. In OSS, this person tends to be the codebase owner, and yet it could take them days or months to review your changelist. In the corporate world, where teams are of different sizes, things could get more complicated to find the right person for review.
You need feedback in timely manner
I have many times experienced situations where Pull-Requests stay open for a long time – days, or even weeks – without anyone taking a look at them. This becomes frustrating in many ways:
- you have to re-sync your changes on a regular basis and resolve possible conflicts;
- you have to switch contexts because you would have moved on to another task;
- your changes are not reaching production.
Value stream mapping, a lean manufacturing technique to optimize the flow of bringing a product to a customer, identifies this as waste:
Much of the waste in knowledge work occurs in the handoffs (or wait time) between team members, not within the steps themselves. Inefficient handoffs lead to low productivity and poor quality.
There are guidelines for writing Pull-Requests, which would make your changelist easy to review, however in this post I want to focus on who does the actual review. Based on my own experience and the responses I got on Twitter, I have identified the following major strategies.
One person to rule them all
In OSS, especially projects driven by a single person, the codebase owner becomes the de-facto reviewer for everything. In the corporate world and some bigger OSS projects, there might be a dedicated go-to person, usually the most senior developer in the team.
- High consistency in code quality
- If the person enforces their opinion without adequate arguments, other team members might become frustrated and this could affect the teamwork.
- This go-to person might experience a high level of stress as they won’t be able to afford taking days off or sick leave easily.
You choose the reviewer explicitly
You are responsible for choosing the best person to review your changes. How could you choose one?
Based on the complexity
Depending on how complex your changes are, you might choose a more senior or a junior person to give you feedback. What I find difficult is to decide about complexity. The more experienced you become, the better you get at it. Yet, complexity is subjective and if you have many people in your team, it could be a hassle to find the appropriate one.
Based on the nature of your changes
If your changes could be assigned to an isolated part of the system, which someone else has worked on before, it would be natural to ask that person for feedback. This works well if you have been in the organization for some time and know the system well. However, if you are new, you might struggle to find the creator. Version Control Systems do help by providing a log of changes (GitHub can even suggest reviewers based on git blame data) and yet, it could be difficult to choose the right person, when many developers have worked on the same feature. Moreover, the person might not be part of the organization anymore.
Based on your gut feeling
In the end your gut feeling plays a role in choosing a reviewer. The decision could be based on things like:
- who you like most on the team;
- who you would expect to find time for you;
- who you would expect to review your changes quickly.
- You have the power to choose the person to give you feedback. However, with great power, comes great responsibility (see below).
- If you happen to work under pressure to release features quickly, you might find yourself in a situation where you always choose the same reviewers, because, for example, they tend to merge your changes quickly. In such situations, one of the most important aspects of Pull-Requests – learning – is lost.
- You have created your Pull-Request and you write to your colleague to review it a.s.a.p. However, at this time your colleague is working on something else, maybe even they have established a flow. So you are definitely going to distract them and possibly annoy them.
Everyone in the team does reviews
Instead of you choosing explicitly a reviewer, you would just create your Pull-Request and people from the team would go over and check it.
- You encourage everyone in the team to participate in the reviews, even the junior members.
- You increase the spreading of knowledge as everyone can follow what is going on in your system.
- People could feel overwhelmed with all changes coming as Pull-Requests.
- When everyone works under pressure, no one would care for your Pull-Request and you would resort to manually choosing a reviewer.
To make this strategy work, I have found out that you need to make reviews a habit, part of your organizational culture. For example, I like starting the day with reviews. I do this occasionally during the day too.
Reviews at scale
When working at scale, the above techniques might not always help you. Google’s codebase has more than 2 billion lines of code with more than 40,000 commits on a regular workday. In the book Software Engineering at Google the authors describe Google’s code review tool, Critique, which, similar to GitHub, can propose sets of reviewers that are sufficient to approve a changelist based on:
- who owns the code being changed;
- who is most familiar with the code (e.g., who changed it most recently);
- who is available (e.g., not on holiday).
To work at scale, you need a solid support from your tools.
Pull-Requests are a mechanism for collaboration. Some of the benefits are raising awareness, spreading knowledge, and exercising control over what is merged in the codebase. Whatever technique you choose for the Pull-Request reviews, you need to establish a culture in the team. The team goes through different phases and you need to observe their behavior and adapt accordingly.
Moreover, to grow as an organization, you have to learn. Pull-Requests offer a great opportunity for everyone, disregarding of their level of experience, to learn from each other and become better at their daily duties. With this, the whole organization becomes smarter.