What is a pull request?
by Mark Johnson on 8 November 2013
Introduction
A pull request is a method of submitting contributions to an open development project. It is often the preferred way of submitting contributions to a project using a distributed version control system (DVCS) such as Git. A pull request occurs when a developer asks for changes committed to an external repository to be considered for inclusion in a project’s main repository.
It is important to note that “pull requests” are a workflow method, and are not a feature of the version control system itself. This document will provide a simple overview of pull requests and how they are created, using the Git version control system and GitHub hosting site as examples.
Making a change
When contributing to an open source project using a DVCS, you will have a copy or “clone” of the source code repository in your local development environment. Here, you can make your changes and commit them locally to create a revision history, allowing changes to be tracked and easily rolled back if required. Changes committed locally can then be submitted to the upstream project for inclusion in the next release.
Once the contributor is satisfied that their changes are worthy of consideration by the project maintainers, a pull request is raised.
Raising a Pull Request
The method for rasing a pull request may differ between projects, so be sure to check the projects documentation for details. However, projects using GitHub will often use GitHub’s own tools for handling pull requests. A common workflow for submitting a pull request with GitHub would look like this:
- Create/Log in to your GitHub account
- Go to the page for the code respository you want to contribute to (the “upstream”)
- “Fork” the repository (this creates a clone to your GitHub account)
- Create a local clone of your fork with
git clone - Create a local branch for your changes
- Make your changes and commit them to your local branch with
git commit, ensuring to include a descriptive commit message - Push the branch to your GitHub fork using
git push - Go to the page for the upstream repository go to the pull requests tab
- Click the “New Pull Request” Button
- Select the branch you want to submit, and write a summary of what your change explaining what it is intended to do and how it is implemented
Other projects may handle pull requests outside of github, for example Moodle manages pull requests as tickets in its Jira bug tracker. However, you’ll always need to push your changes to a publically accessible repository for your code to be accessible by the project, so having an account on a site like GitHub or Bitbucket is a good idea.
Applying a Pull Request
Once a pull request has been submitted by a contributor, it is then the responsibility of the project maintainers to evaluate and, where appropriate, merge it into the upstream respository. Different projects have different approaches to reviewing and applying pull requests. However, they all have some common steps:
- Quickly evaluate the value of the changes
- Prepare prompt and accurate feedback to the contributor (requesting a resubmission where appropriate)
- Check out the changed code and run any test suites against it
- Report any problems to the contributor and request a resubmission
- Pull the changes into the upstream code
Skilled developers can read diffs (textual representations of the changes made) and understand their implications without actually applying them to the code base. GitHub provides a view of the diff describing each pull request to make this easier. This makes it easy to provide rapid feedback to the contributor. Should the project maintainer feel that the change looks like a solid contribution, they will check out the branch for which the pull is being requested to their local development environment and test it. Since a good contribution will already have undergone extensive testing, this should be a simple matter for the maintainer. However, mistakes can be made and so further testing should always be carried out.
Once a pull request has been approved the maintainer will pull it into the requested branch of the upstream repository, either using GitHub, a git merge or git pull command. This will make the code available in the public version on the upstream repository. If this change is assocaited with an ticket in the issue tracker, the ticket should then be updated. GitHub allows this to happen automatically by referencing the issue in the commit message.
Is it really that simple?
It is important that changes are made against the latest version of the code in development. In git, this is usually the branch called “master”. If there are stable releases still receiving bug fixes and updates, you may want to consider whether you should also submit a pull request for your changes against those versions, which will often have their own branches in the upstream version control. If the changes fix a bug which only occurs in an older version, then it may be appropriate to only submit a pull request against the older version.
It is also important that the contributor ensures that the changes made comply with any documentation and coding standards adopted by the project. It is also critical to thoroughly test changes against any test suites the project provides. Finally, each contribution should be clearly documented with, at a minimum, details on:
- What it is intended to do
- How it is implemented
- How it is used
For more about the rationale behind this and the importance of submitting your changes upstream, read the Is It Really That Simple? and Why Should I Contribute A Patch? sections of our breifing, What is a Software Patch?
Further reading
Links:
Related information from OSS Watch: