With the name of our company being PullRequest, we get many questions:

• What is a pull request?
• Why should I use pull requests?
• How do I create a pull request?
• Whats makes a good pull request?

What is a Pull Request?

In its most simple form: A pull request is a request to have changes merged into a repository or project.

The changes being proposed could be as simple as fixing a minor typo, or as complex as adding hundreds of files with major changes to the project. When a pull request is initiated, maintainers of the project are able to review the proposed changes, suggest edits, and approve the proposed changes to be merged. This process of reviewing the changes before they are merged is called “code review”.

Some use the term “merge request” instead of “pull request” which essentially describes the same process of requesting that a set of changes be merged into the project. For example, GitLab Merge Requests assume the same exact role as GitHub Pull Requests.

Pull Request Tools

There are many variations of pull requests, as it is a somewhat generic term used for this process of proposing and then merging changes. However the most commonly used are those found in code hosting services like GitHub, GitLab, Bitbucket, and Azure DevOps.

These are all applications based around the version control software Git. Git facilitates tracking changes made to a project over time, but it does not provide the mechanism for reviewing and leaving inline feedback to proposed changes. So services like GitHub build these layers of collaboration on top of the underlying version control software.

Code Authors and Code Reviewers

The author(s) of the pull request are the one or more people who have made the changes to the project being proposed. The reviewer(s) are usually teammates or co-collaborators with the author(s) and are responsible for reviewing the proposed changes. There are many ways of deciding who should review the changes that vary across projects. Some larger projects have a limited number of “maintainers” who are a defined set of reviewers that are allowed to approve changes to be merged into the project. Other projects allow anyone except the author to approve changes to be merged.

Why Use Pull Requests?

The main reason to use pull requests is to facilitate a beneficial code review process. A project can quickly become a mess and have many issues if everyone on the team is allowed to edit code without gathering feedback and ensuring quality. Code review is proven to help hold the standard of the project to a higher level and reduces the number of issues that get merged into the project. More on the benefits of code review.

Pull requests provide an excellent point in time to get feedback from various stakeholders. Many high performing teams will not only have the author’s peers review their code, but it also facilitates adding more senior engineers or security experts to the pull request help ensure there are no issues being introduced depending on the changes being made. For example, teams benefit tremendously by using PullRequest to bring in experts to review proposed code changes on-demand.

Pull Request Lifecycle

Although a pull request usually starts off with just a set of proposed changes, it will often go through several iterations until it is ready to be merged. The first step after the pull request is created is for a reviewer to look over the changes. A reviewer’s job here is to help ensure that the changes being proposed won’t introduce any new issues, implements the intended functionality, and doesn’t degrade the quality of the project. The review process is also a good time to share knowledge and learn as both the author and reviewer.

Pull requests that make very simple changes can often approved without any follow-up revisions and will have minimal, if any, feedback. An example of this could be a pull request that fixes a simple typo. However, this should be avoided for larger change sets that contain more complex updates. These pull requests tend to be larger and require several iterations where a reviewer leaves suggestions and then the author replies and makes any necessary updates to their proposed changes. These updates are committed to the same branch that the pull request was initially opened for. This allows reviewers to monitor and track the updates made to the branch to confirm that the issues raised have been adequately addressed.

Once the reviewer is satisfied with the quality of the changes being proposed, they’ll typically “approve” the pull request. An approval means that the reviewer thinks that the author’s changes can be safely merged into the project. Projects can be configured to require one or more approvals before the changes can be merged. The reviewer also has the option to not approve the changes and sometimes pull requests will be closed or rejected instead of merged if it is decided to be better to not introduce these changes.

What Makes a Good Pull Request?

Not all pull requests are as effective at facilitating code review. The most important criterion that makes a good pull request is that it is focused. If you open a pull request that contains many different unrelated changes, then the burden on the reviewer becomes much harder as they must keep context switching when reviewing. It’s difficult to catch issues in a pull request that’s difficult to review. In order to reduce the cognitive load on your reviewers to gain the most out of your code review process, try to minimize the line count of changes being introduced and focus on a single feature or bug fix at a time. The effect of code review size on cognitive load is described in more detail with our code review benchmarks guide.

Good pull requests also contain good descriptions. Leaving a thorough description will help reviewers more effectively understand the intent of the proposed changes. We wrote up a guide on creating a great pull request description.

Creating a Pull Request

There are several main components required to create a pull request in most of the code hosting services like GitHub. The first is that you need to have your changes developed and committed to a branch in Git. There are several ways to do this, and some of the code hosting services will let you do this all from their web applications for smaller changes. However the most common method is to use Git. Git has a bit of a learning curve, so if you are completely new to it then it is recommended to do some tutorials to get up to speed.

Here’s a simple example of the commands used to commit changes to a branch in a repository from the command line:

# clone the repository
git clone <git repository>

# create a new branch called “new-feature” and check it out
git checkout -b new-feature

# now edit one or more files locally within this repository

# add your edits to your staged changes
git add .

# commit your changes to your branch with a commit message
git commit -m “creating changes for the new feature”

# push the changes from your local branch “new-features” to the remote repository
git push origin new-feature

This saves changes to the “new-feature” branch in the remote repository. When changes are committed, you can go to GitHub, or wherever your git repository is hosted, and create a new pull request using the new-feature branch.

When drafting a pull request, you’ll be able to add the description as well as a title. We covered the value of a good pull request description above, but it’s worth noting that a good pull request title can be just as helpful for reviewers to understand the intent of the proposed changes. It also helps keep the repository’s history of pull requests descriptive and well-organized.

The best way to master pull requests is to practice them. Be sure to get experts, like the engineers from PullRequest, involved in your pull requests as reviewers.