How to manage pull requests

You are one of the managers of a large project.  Other people
want to contribute, so they send you pull requests.  The pull
request is GitHub's way of letting other people contribute to the
project, while still allowing you to have complete control.

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" version,
not your own personal fork of the project.

It is common to see 7 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 did 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 (e.g., "added problems 7.5 to
7.9 on page 88").  Let's assume they gave a clear description,
and what they describe sounds like something good.

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?  Well, a "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.  If they both submit pull requests, after you accept
one of the pull requests then the other will have a
conflict, because there is no automated way to figure out how
to merge the two sets of changes.  (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 problems to a problem list.  Once you accept one
pull request, there is no automated way to determine where to
put the second set of new problems.

A merge conflict requires a human to figure out what to do.  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, the usual thing to do is
scroll down to the next item on the page, which is a comment box.  Write
a brief message saying there is a conflict, and click the Comment
button.  An email will be sent to the person who submitted the pull
request.  You should expect them to fix the conflict and re-submit.
(Occasionally you may choose to fix the conflict yourself, but let's
not worry about that now.)

The way that person will fix the conflict is: checkout the branch where they
did the work in the pull request, then do

git pull upstream master

so that they have the recent changes done by other people.  When they
do that they will get a message telling them about the conflict.
After fixing the conflict they will add, commit, and then push to
their fork.  Then *automatically* the pull request will be updated
and you will be able to proceed to the next step.

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 didn't close it 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 changes they made.  There are three tabs below the title of the
pull request:

Conversation    Commits    Files changed

Click on "Files changed".  Highlighted in pink and green will be the
lines which were deleted and added as part of this pull request.  You need to
look carefully at what was written, because this is going 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:

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

The author has mis-used a LaTeX macro, 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 their changes and the format and content
seems to be okay, now you need to actually check that their contribution
performs as claimed.  If the project is code, that means you need to
run their code.  If it is a book, you need to compile the book with
their changes and see that the output looks good.

Click back to Conversation, and next to the big green "Merge pull request"
click on the blue words "command line instructions".  You will use the
two commands which appear in Step 1.  But before you do that:

Go to the version on your laptop, and do

git checkout master
git pull upstream master

You should be in the habit of doing that whenever you are about to start
something new, so it shouldn't be a surprise that you are supposed to do
that now.

Then do the two commands in Step 1 on GitHub, which will look something
like this:

git checkout -b fredstro-maass_pictures master
git pull https://github.com/fredstro/lmfdb.git maass_pictures

# a person with username "fredstro" made the pull request from
# their branch called "maass_pictures".  the above two commands
# created a new branch on the laptop called "fredstro-maass_pictures"
# and then checked out (i.e., switched into) that branch, and then
# pulled fredstro's pull request into that new branch.

Now you can do a thorough check on the pull request.  Compile latex,
or run code, or whatever is appropriate for your project.  Examine
the output to see if it performed as expected.

If it fails, perhaps there was a LaTeX error, then leave a comment under
Conversation and the person will fix it.  That scenario is quite common:
people often forget to actually run latex or check their code before
submitting a pull request.  (It can also happen that the person handling
the pull request fails to actually check everything before accepting
the pull request.  The real blame lies with the person who accepted the
request, because they are in a position of responsibility for the project.
So be very careful if you accept a pull request after only glancing at
the Files changed on GitHub.)

If everything looks good, then go back to GitHub and click the big green
"Merge pull request".  Modify the message if necessary, and then click
"Confirm merge".  It may then say something about deleting a branch
which is no longer needed: that is a fine thing to do.

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

Note that your laptop is still on the temporary branch you created to
check that pull request.  So you should checkout master and
git pull upstream master.
The master branch on your laptop will now have the changes from the
pull request you just accepted.

If you handle a lot of pull requests you will acquire a lot of branches
which are no longer needed.  Do
git branch
to list all the branches, and 
git branch -d branchname
to delete a branch.  The temporary branches you make when you evaluate
a pull request have distinctive names, which makes it easy to identify
and delete them.