Saturday, December 29, 2012

Pull Request and Code Review in GitHub's Shared Repository Model

Many people do not realize that you do not have to fork a repo in order to do pull requests and code review. In GitHub's shared repo model where a team of people have equal access to a single repo, pull requests and code review can be done between two branches of the repo. The basic workflow is creating a new branch, making pull requests from this new branch to master, and after your changes are accepted, merging them into master and deleting this temporary branch. David Winterbottom wrote a post about this workflow at http://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github. I added some of my understandings, and simplified this workflow according to my common use-cases:
  1. Creating a new branch: Say the new branch is called "feature". git checkout -b feature
  2. Make your changes. 
  3. Commit your changes using "git commit". You can commit multiple times. It does not quite matter, because these changes are on this separate branch. You can later merge them into master however you want. 
  4. Push your changes: git push origin feature
  5. Go to the project's GitHub page, and issue a pull request. Make sure you pick "master" as the base branch, and "feature" as the head branch. 
  6. Wait for your changes to be accepted. If you are asked to revise your changes, go ahead editing your branch and pushing your new changes. GitHub will automatically update the pull request to contain your new changes, so you do not need to issue another pull request. Note that when you commit your new changes, you should not use "git commit --amend" because your old commit is already pushed. Also, do not worry about multiple commits in your branch, because you can later squash them when merging them into the master branch. 
  7. Clean up your history: git rebase master. This command rebases your changes on top of master, so that the later merge to the master branch can be fast-forwarded. If you did not sync the branch branch after branching (step 1), this command likely does nothing and simply shows the current branch is up-to-date. 
  8. Merge your branch into master. First, switch to the master branch using "git checkout master". Second, "git merge feature" or "git merge --squash feature". The latter command squashes all the commits into one commit, which is recommended because these commits most likely achieve the same goal. If you go with "git merge --squash feature", you need an extra "git commit" and modifying the commit message. 
  9. Push your changes to the master branch: git push. You may need to "git pull --rebase" and resolve some conflicts if your local master branch is older than the remote one. 
  10. Delete the branch you created: Now that you have pushed your changes to master, you can happily remove the branch you created. First, delete it from your local repo using "git branch -D feature". Second, push the deletion to the remote repo using "git push origin :feature"

2 comments:

Sam Dutton said...

Thanks! Really clear explanation.

Gunnarr Baldursson said...

I like! This is what I was looking for.