Pull Requests for Dummies
Debate about code reviews is often dominated by debate about pull requests. The confusion between the two is so common we have made it a point to clarify that they are not the same quite often. So what are pull requests? And why are they called that way?
Imagine you’re writing a book.
In this case, you’re writing collaboratively. Let’s say it’s a non-fiction book, or a technical manual. Something that requires a certain degree of responsibility and accuracy.
You will need to figure out a strategy to make sure there are as few mistakes as possible.
How about… version control?
If this is a collaborative work, then it stands to reason that you will want to keep your file (let’s say a Word document) somewhere everyone can easily find it and work on it. Let’s say you keep your manuscript on Dropbox.
You (or any one of the other authors) are working on a specific chapter, so you download the manuscript that the team is keeping online. You would never edit the manuscript directly, that would be way too risky. You create a temporary version, and label it as such.
You do your work, write your lines, make sure everything is to your liking, and then what do you do?
You upload it to the Dropbox, always making sure that it’s labeled correctly as a temporary version. Why? Because you would like feedback from your colleagues before pulling everything together (notice our word choice there 🧐).
What’s a simple word for asking for feedback?
Dictionaries are interesting.
Anyway, your colleagues will then look at your brand new text and they will carefully look over it. They will correct mistakes, leave notes and suggestions, make recommendations, and, of course, if all is well, simply accept it.
When this is done, and the author of the new chapter is confident he’s answered all the queries and fixed all the problems, they can then request whoever is responsible for the manuscript to pull his changed text into the main document.
And that is what a pull request is.
When a developer finishes a task, they will start a process to join the new code to the project. For that purpose, they will ask whoever’s in charge of the project to pull the changes from their working branch to the main branch. Voilá, a request to pull changes: a pull-request.
So it’s not a review, but it implies a review?
Most of the time, yes.
Unless the changes are very trivial, it would be irresponsible to pull changes into the main branch without performing a code review.
What happens frequently is the opposite: code reviews happen all the time without the need for a pull request.
A developer might want to review the changes between different states of a project for many different purposes:
- Auditing the source code is always important;
- Reviewing code without making it visible to everyone else in the project (pull-requests are always visible), for whatever reason;
- Reviewing the code when the project is scattered across many repositories;
- There are even some software development methodologies that don't use pull requests at all! And they still review code.
We hope this helped clear up what pull requests are, and why they are often wrongly mistaken for code reviews. Are there any topics you’d like us to cover next on this series?
If so, you know where to find us on Twitter (@reviewpad)!