Profile

Cover photo
64 followers|34,449 views
AboutPostsPhotosVideos

Stream

OSS Watch

Shared publicly  - 
 
This is the new Google+ page for OSS Watch
4
2
щйібгь гбіий's profile photoOciel Vazquez's profile photojaneth Olvera's profile photo
3 comments
 
Skip to NavigationSkip to Content




OSS Watch provides unbiased advice and guidance on the use, development, and licensing of free software, open source software, and open source hardware.

If you want to find out more about any of these topics,we're the people to ask.

@osswatch +osswatch +44 (0) 1865 283416

Toggle navigation

Home > Resources > Briefing Notes> What is a pull request?

What Is A Pull Request?

by Mark Johnson on 8 November 2013

A pull request is a method of submitting contributions to anopen development project. It is often the preferred way of submitting contributions to a project using a distributedversion 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 andGitHub 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 accountGo 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 cloneCreate a local branch for your changesMake your changes and commit them to your local branch with git commit, ensuring to include a descriptive commit messagePush the branch to your GitHub fork usinggit pushGo to the page for the upstream repository go to the pull requests tabClick the “New Pull Request” ButtonSelect 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 changesPrepare prompt and accurate feedback to the contributor (requesting a resubmission where appropriate)Check out the changed code and run any test suites against itReport any problems to the contributor and request a resubmissionPull 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 orgit 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 onlyoccurs 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 doHow it is implementedHow 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:

GitHub help - Fork a RepoGitHub help - Using Pull RequestsMoodle Development Process

Related information from OSS Watch:

Release management in open source software projectsContributor Licence AgreementsWhat is version control? Why is it important for due diligence?Can you contribute code to an open source project?How to build an open source communityRoles in open source projectsWhat is a Software Patch?



Mark Johnson 
Mark is Development Manager at OSS Watch, and co-presenter of the Ubuntu Podcast



Jump to section...

Making a changeRaising a Pull RequestApplying a Pull RequestIs it really that simple?Further reading

INFORMATION FOR

NewcomersAcademic End UsersSoftware DevelopersIT Managers And Technical StaffStrategic IT Decision Makers

RESOURCES

Strategy And PolicyOpen Source Software DevelopmentIntellectual Property Rights (IPR), Licensing And PatentsBuilding CommunitiesCase Studies

 

Unless otherwise indicated, this page is © 2007-2014 University of Oxford. 
What is a pull request? by Mark Johnson is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License .

OSS Watch values your input and questions. If you have feedback on this document, or any OSS Watch activity, please send it to: info@oss-watch.ac.uk.


Add a comment...
Story
Tagline
Independent expert advice on open source software
Introduction
OSS Watch provides unbiased advice and guidance on the use, development, and licensing of free software, open source software, and open source hardware.
Contact Information
Contact info
Phone
+44 (0) 1865 283416
Email