Git for Authors

GitHub has likely sent you a notification immediately after a contributor has created a pull request, and maybe that email has a link to take you directly there. But you also need to know how to find any given pull request later.

Go to the project’s home on GitHub and see if there are any pending pull requests. Note that you are going to the definitive repository, not your own personal fork of the project. You have your manager-hat on now, not your contributor-hat.

It is common to see seven tabs across the top of the repository on GitHub:

Code  Issues  Pull requests  Wiki  Pulse  Graphs  Settings

The first three and the last one are used most often. For Issues and Pull requests there will be a little number telling you how many items need your attention. Click on Pull requests. Each pull request will have a title, and it will tell you who made the pull request and when they created it. Click on one of the pull requests.

If the contributor did a good job, there will be a few sentences describing what they did, and an indication of how their proposed changes appear in the final product, such as “New exercises for Chapter 6, see page 88.”. Let us assume the contributor gave a clear description, and what they describe sounds like something beneficial to your project.

Below the description you should see a check mark in a green disk, and the phrase

This branch has no conflicts with the base branch

What does that mean? A merge conflict occurs when two people modify the same part of the same file. This could happen, for example, if a definition had awkward wording, and two people decided to fix it at about the same time. If they both submit pull requests, and you accept one of the pull requests, then the other pull request will cause a merge conflict because there is no automated way to figure out how to apply the second set changes since the original context has been destroyed by the application of the first pull request. (In the unlikely case that both people use the exact same wording then there would not be a merge conflict.) Another common scenario is when two people add new exercises to the end of an existing list. Once you accept one of these pull requests, there is no automated way to determine where to put the second set of new exercises. Should the second group of exercises go before the first addition, or after the first addition? git cannot help you here, and therefore will not help you.

Another likely explanation is that the pull request has a branch with a long lifetime. It was created as a branch off the tip of master, but that was a long time ago. The contributor added commits at a leisurely pace, and the overlords took their time in getting to their pull requests (always a bad practice for an overlord, you want happy contributors!). During this time, conceivably many new commits have been added to the master branch and somewhere there is an unfortunate overlap with the contributor’s edits or their context.

So a merge conflict requires a human to figure out how to resolve it. Usually it is simple: just look at both versions and choose one, or the other, or come up with some happy medium. Simple for a person, but impossible for a machine.

When GitHub says there is a merge conflict, it is because GitHub has done a trial test of merging your branch in the pull request into the master branch of the definitive repository and the trial ended badly. The usual thing to do is scroll down to the next item on the page, which is a comment box. Write a brief message to the contributor saying there is a merge conflict, and click the Comment button and an email will be sent to the contributor. You should expect the contributor to resolve the conflict (see next paragraph). Occasionally you may choose to fix a small conflict yourself, but let us not worry about that now.

The contributor can resolve the conflict by doing

git checkout <branch_name>
git pull upstream master

So the contributor is on the branch they offered in the pull request, and it is important to get this part right. Then the contributor pulls commits from the master branch of the definitive repository. Several things happen as a result. First, the contributor gets the very latest commits from the master branch of the definitive repository, so it very up-to-date. Then git will try to merge master into <branch_name>. This is going to end the same way as it did in git’s trial: badly. But we expected it, were prepared for it, and git will do everything it can to help us.

The merge of the commits pulled from master, into the contributor’s branch will cause a merge conflict. See Chapter 5 for the general procedure for resolving a merge conflict. Once that is done, the contributor can now push their branch to their fork at origin and GitHub will notify the overlords that the updated branch is ready for review.

Note: there is no need to click Close pull request. Only do that when you really intend to reject the request. And always leave a message so that it is clear you did not close the pull request by accident.

Now you are looking at a pull request with a description that sounds useful, and there are no conflicts. The next step is to look at the actual changes the contributor made and their effect on your project. There are three tabs below the title of the pull request:

Conversation    Commits    Files changed

Click on Files changed. Highlighted in red and green will be the lines which were deleted and added (respectively) as part of this pull request. You need to look carefully at what was written, because this is destined to become an official part of your project. All large successful projects have standards for writing the source material, and you should check that the author has done a good job. Suppose, for example, you see the following line added to your calculus textbook:

When finding a maximum, be sure to check {\em both} end points.

The author has not used the LaTeX markup language in the best way, so it would be reasonable to click back to the Conversation tab, and in the comments box put something like

Use \emph{...} instead of {\em ...} for emphasis.

It is a good idea to look through all of their changes and submit multiple comments (in the same comment box), otherwise both of you will become annoyed if you have to go back and forth several times.

Assuming you have looked through the contributor’s changes and the format and content seems to look okay, now you need to actually check that their contribution performs as claimed. If the project is code, that means you need to compile and run their code. If it is a book, you need to produce the book with their changes and see that the output looks good. Here is the procedure for doing a preliminary review within your fork on your laptop (this is your personal sandbox) and then actually incorporating the changes into the definitive repository.

That is it! More than ninety percent of pull requests can be handled with those simple steps. If you encounter a complicated situation, seek help from an expert.