Making Pull Requests

[Jeff Verkoeyen]

Hey everyone,

I want to give some quick tips on making pull requests on GitHub. I've noticed over time that some pull requests get quite hairy because the process on GitHub can be a bit unintuitive at first.

So to begin, I want to direct you to the Pull Request information we've put together on Three20.info:

http://three20.info/article/2010-10-24-Branches-And-Cuts#pullrequests

I want to provide some additional information here as well.

Every pull request requires two branches: the "base" branch and the "head" branch as GitHub terms them. I don't particularly find this terminology that intuitive, so let's go ahead and call them the "destination" and "source" branches, respectively. The destination branch is the branch you intend to merge your source branch's changes into.

Every pull request should always use "development" as the destination branch. To learn more about why this is the case, please read about our primary branches here:

http://three20.info/article/2010-10-24-Branches-And-Cuts#primarybranches

When you issue a pull request, you must provide a source branch to be merged. This branch should contain a set of atomic changes that only apply to the pull request in question.

A nice feature about GitHub's pull requests is that they automatically track changes to the source branch and add them to the pull request. This feature can quickly turn into a confusing mess, however, if the repercussions of it aren't completely understood.

Let's consider a quick example that I've seen a few times now.

Fictitious George wants to submit a few changes he made to Three20 on his master branch. He pushes his master branch to his personal Three20 repo and issues a pull request to facebook/three20:master from george/three20:master. He checks out the included commits and everything looks ok. Pull request issued, everyone gets cake.

But as many of us know, the cake is a lie. George finds another bug in Three20 and decides he wants to submit another pull request. He runs through the above process again, pushing his master branch to his personal Three20 repo and issuing another pull request from this new commit SHA1.

Now he has two pull requests, one from master, the other from a specific commit SHA1. But remember how GitHub tracks changes to branches? With more changes pushed to master, Pull Request #1 now includes both commits! Definitely not what was intended.

In order to avoid this problem, George can simply do the following:

git checkout 1.0.4              # Or whatever version of Three20 you're working from

git checkout -b fix-ttstyle-bug # Create a new branch titled "fix-ttstyle-bug"

git commit -a                   # Commit your changes

git push origin fix-ttstyle-bug # Push the branch to your personal repo

# Issue pull request to facebook/three20:development from username/three20:fix-ttstyle-bug

If there is any feedback about the pull request:

git checkout fix-ttstyle-bug    # Make sure we're working on the right branch

...                             # Make the file modifications

git commit -a                   # Commit the changes

git push origin fix-ttstyle-bug # The Pull Request will automatically be updated with this new commit

Once your pull request has been merged into development, you have two options:

1. Wait for the next release and then check it out.
2. Fetch the merged changes in development and rebase your local changes on top.

Option #2:

git fetch facebook              # Get the latest data from facebook/three20

git checkout development        # or whatever branch you do your work on

git rebase facebook/development # Rebase your current branch on top of facebook/development

Hopefully this helps clear up how Pull Requests work on GitHub a bit. I'll probably put together a screencast that walks through a number of standard scenarios because I have a feeling that that will be a bit more helpful than a wall of text.

Cheers,

- Jeff