Pull Requests are a feature of online git services like Github and Gitlab. They allow anyone to request for changes to be added, even if they don’t have access to the repository. We’ll discuss how they work, and how to use them for open source collaboration.
What Does a Pull Request Do?
Despite how it may seem,
git as a tool is a completely decentralized system. What that means is that the repository on Github.com, and the repository on your local machine, aren’t any different from one another. You’re not connecting to Github to work on a repository, you’re copying the code from Github into your local repository, and working on it there.
When you want to push changes, you can make commits and run
git push, sending your updates to a given “remote,” which can be any other Git repository, but usually is an online hosted service like Github, Bitbucket, or Gitlab. This updates the remote repository to be in sync with your repo.
However, this only works when you have permission to push commits, usually configured with a password or SSH key. This is only given out to members of the organization in control of the repo, otherwise, everyone could alter the Git history. If you’re not a member of the organization, what are you to do when you want to make changes?
Well, there’s a second way that a Git repository can get updated—
git pull. You probably do this a lot whenever your coworkers make changes that get pushed. In that case, you’re pulling down commits from the remote repository, and syncing it with your local repo.
But, Git is decentralized, so there’s really no difference between your repo, and the remote repo. You can actually run
git pull in reverse, from the server, and this is the heart of what makes pull requests function.
A pull request is just you telling the remote server (and the people who maintain it) that you have some updated commits that you would like them to look over and integrate with the remote repository. If they accept the changes, the remote repo will run
git pull against your local repository, integrating the code without you ever having to have an SSH key authorized to do so.
The Backbone Of Open Source Collaboration
Pull requests are used constantly for open source libraries. After all, much of the reason for open source is that any developer can contribute to the project if their code is useful.
Pull requests are what makes that work. The project’s maintainers, the administrators in control of it, are the ones that typically review pull requests and decide whether or not to integrate the code, or whether certain bugs need to be fixed before it’s ready.
Pull requests aren’t exactly a feature of
git itself, so the exact implementation of them will vary depending on the service. But, for Github, you’ll find pull requests in the menu bar of a repository, which shows a list of open and closed requests that you can filter through.
If you click on any one of them, you can view the comments made by the requester, as well as the commits associated with it.
If you’re the maintainer of the repository, you can review and merge the request. Or, if you have issues with it you need to discuss, you can leave a comment and work on the code together. This is a big reason why public spaces like Github are great for open source collaboration, even something as simple as changing the wording of the documentation can be done collaboratively by anyone.
Pull requests are different from issues. Issue tracking is a feature of many services like Github that allows easy bug fixing and public collaboration for new features. Essentially, each issue has a topic that can be discussed by the maintainers and the community. For example,
dotnet/csharplang is the official repo for discussion around how C# as a programming language is designed. If you go to the issues, you’ll find many people discussing concepts for future iterations of the language:
Not all issues lead to pull requests. If the issue is fixed by the maintainer, it won’t matter. If the issue is fixed by a collaborator, they will need to submit a pull request.
All pull requests are either denied or lead directly to code changes in the repository. Issues are just a way to track development progress and which bugs need to be fixed.
Making Pull Requests
Again, the exact steps for this will vary depending on the service you’re using, but most open source collaboration happens on Github, so we’ll show the steps for that.
Head over to the repository you want to make a request for and click “New Pull Request” under the Pull Requests tab:
You have two options here. If you’re a member of the repository, and want to merge your feature branch into the master branch, you can select the two branches.
If you’re working on an open-source repository, you will need to fork the repo, and push it to Github under your own account. Then, you can select “compare across forks” to merge your master branch into their master branch.
Once done, the pull request will be open for discussion, and you will simply have to wait to hear back from the maintainers.
In the meantime, you can check on the status of all pull requests you’re involved in with the “Pull Requests” tab in the main header bar.