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.
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.
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.
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.