Pull Requests 101

I think it is fair to say that pull requests were made popular by GitHub and their brilliant implementation of the concept. Used in a strategic way, pull requests are a very powerful collaboration tool to have in your toolbelt – especially if you work in a team.

According to OSS Watch, a pull request “is a method of submitting contributions to an open development project“. But a pull request can be more than that. If you really adapt pull requests into your workflow, they provide a great space for teams to communicate, collaborate, educate and onboard new team members. This is now the norm in most open source projects, but many development teams – especially in the WordPress sphere – are not even using Git yet. If your team have not yet adapted Git (or another version control system) into their workflow, they are simply lacking the most basics of collaboration tools. The abillity to discuss and review code changes in a pull request is just one of many reasons to use Git, but it is definitely one that is big enough on its own.

The anatomy of a pull request

In order to understand and utilise pull requests, we need to understand the concept of branching. In Git, a branch literally refers to a branch of the code which we can work on in an isolated manner. If we work on a new feature branch, all the changes to the code base will not be affecting our master branch. A pull request, in its simplest form, is the concept of requesting a merge of the differing commits between 2 branches.

In this post, I am focusing on GitHub and the way they have implemented pull requests. On GitHub, a pull request consists of 3 parts:

  1. The merge request of the 2 branches (base and compare)
  2. A diff between those 2 branches
  3. A discussion area

The merge request is the intent of the pull request. Someone wants to add or change something in the code base, which will eventually end with a merge of the 2 branches. In the diff, we have a visual overview of what have changed in the commits applied to the compare branch. The way I work with pull requests, most of the time this diff will be a work-in-progress. Finally, the discussion area is where team members can discuss the proposed changes. This works very much like a normal “issue” on GitHub.

Submitting pull requests on GitHub

As soon as you push a new branch to GitHub, you will be prompted to do a pull request:

GitHub pull request prompt.

After clicking the green button, you will have to specify which 2 branches to compare. The relevant branches are most probably pre-selected for you. The base branch is typically your master branch or another branch containing some kind of larger release. The compare branch is the branch containing the changes you wish to merge.

GitHub pull request creation.

A pull request looks a lot like a normal issue and you have all the same features available. Once you have specified the correct branches and selected a name for your pull request, you will have a discussion area available where you can communicate with your team mates about the pull request.

GitHub pull request.

If you have the right access rights to the repository, you should also see a big green merge button – given the merge does not cause any conflicts. As a part of my video crash course on Git for WordPress developers, I recorded a short screencast on how to submit a pull request on GitHub. You can check it out here:

For more videos on Git, check out my free Git for WordPress video crash course.

A tool for collaboration and communication

When should you open a pull request? As soon as possible and preferably before you even start writing any code.

A pull request is a perfect place to discuss code related topics and give each other useful feedback. When I first started using pull requests, I was a junior Ruby on Rails developer. When tackling a new feature, I would open a pull request on GitHub as the first thing, so my co workers could follow along on my progress. This was a great way for me to continuously get feedback, while finding my way around the code base.

This is not only relevant to junior developers, but to developers with all kinds of different skill levels. A pull request should be a work-in-progress, where you encourage your teammates to give you feedback, support and help you improve. This is how a team is supposed to work.

Do you use pull requests?


Want to read more like this?

Add your email address below to stay in the loop when new content arrives. You'll never miss a post.

Peter Suhm

Peter is a web developer from the Land of the Danes. He is the creator of WP Pusher and a huge travel addict.