CS 257: Software Design

Lab: git workflow

In class. Nothing to hand in.

In this lab, you'll learn about GitHub Flow, a common way for small teams to work effectively with git. GitHub Flow lets individual team members do work that doesn't interfere with anybody else's work, and also provides a collaborative process for merging indviduals' work with the shared central code.

The workflow from Alice's perspective

As with our previous git lab, you should have one person/clone play the role of Alice and another person/clone play the role of Alice's teammate Bob.

• Alice decides she is ready to work on a new feature which will, when complete, cause a swarm of images of one of her professors to rampage (rampage!) across the screen.
• Alice gets her local repository up to date with the remote repository, as much as possible. Typically, this involves first making sure she has no changes to commit, and then:
  git checkout master git pull
  This will make sure that she's using the most up-to-date project code as the basis for her work.
• Alice creates a new branch:
  git branch rampageFeature git checkout rampageFeature
  (The shorthand: "git checkout -b rampageFeature" does both of those steps if you prefer.) Alice likes to let GitHub repository know about her new branches right away, even before she has committed any work to them. So she also does this:
  git push --set-upstream origin rampageFeature
• Alice does some work. Every time she gets to a reasonable pausing place, she uses "git status" and "git add ..." as appropriate to prepare to commit her changes, and then:
  git commit git push
  She repeats as necessary, coding, testing, debugging, etc. and occasionally committing and pushing.

• Alice thinks her feature is ready to be included in the master branch. She makes sure she has committed and pushed all of her work to the rampageFeature branch.

  Then she goes to the GitHub web page for her team's repository and selects the rampageFeature branch:

  

  then selects the "Pull requests" tab and clicks on the big green "New pull request" button:

  

  and finally sets up the "comparing changes" drop-down lists to show "base: master" and "compare: rampageFeature". That is, she wants the rampageFeature changes to get merged into the master branch:

  

  And finally, she clicks on the "Create pull request" button.

• Alice goes off and does something for fun. Coding is great, but sometimes you need to play the tuba or zip-line through the Arb.

Bob gets involved

• Let's assume that Bob has subscribed for pull request notifications (which are on by default, and can be adjusted by clicking on Bob's avatar in the upper right corner of GitHub, selecting Settings, and then selecting Notifications in the left-side navigation panel). Bob will receive an email alert telling him that Alice has created a pull request.
• Bob follows the link in the email and studies the work Alice has done. He can chat with Alice in the discussion thread attached to the pull request. But if he agrees that it's ready for merging into master, he approves it by clicking on the "Merge pull request" button:
  
  and then clicks on the "Confirm merge" button.
• Bob next has the opportunity to delete the rampageFeature branch from the github copy of the repository. He clicks on "Delete branch" to make that happen.

Alice and Bob tidy up

The rampageFeature branch has now done its job. It gave Alice an isolated place to work without messing up the master branch or whatever Bob might have been working on at the time. But once Alice's code is ready to be part of the main codebase and has been merged into the master branch, nobody needs rampageFeature hanging around anymore. It has been deleted from the github copy of the repository, but now Alice and Bob both need to remove it from their local copies of the repository.

So both Alice and Bob do this:

• Obtain the latest copy of the master branch, and remove their reference to the now-defunct remotes/origin/rampageFeature branch.
  git pull --all --prune
  Take a look to see that remotes/origin/rampageFeature is absent:
  git branch -a -v
• Delete their local copy of the rampageFeature branch:
  git checkout master [to make sure they're not in rampageFeature] git branch -d rampageFeature [to delete it]

That's it

In brief:

• You create a new branch, work in it, and push all your commits in that branch up to github
• Ready? You create a pull request.
• One of your teammates does a sanity check on your code, just to get another set of eyes on it. Discussion may or may not ensue.
• The teammate approves the pull request, which performs a "git checkout master" and "git merge rampageFeature" to merge your changes into master.
• The teammate deletes github's copy of the branch.
• All teammates grab all the branch changes from github (git pull --all --prune) and delete the feature branch from their clones (git branch -d rampageFeature).
• Repeat

This blog post gives you more info about how GitHub as a software development team thinks about this workflow. Worth reading if you're interested in more thoughts on the subject. (Note that "git-flow" is an earlier, more complicated workflow than GitHub Flow, more suited to large teams and large projects.)