A Simple Github Workflow

This document describes one of many possible workflows using github, and takes advantage of features added to the github-gem in this fork.

If you are just setting up github you have a bit of work to do.

Register an account at github and it will ask you for your public ssh key (You can always change this later in Account Settings > Account Overview > SSH Public Keys. If you have an ssh key already use this if not generate one with:
ssh-keygen
Then copy/paste the the text from ~/.ssh/id_rsa.pub

Next config git with your information:
git config --global user.name 'Lotus The Cat' git config --global user.email '[email protected]'
You can verify your settings by examining the ~/.gitconfig file

If you are running ruby 1.8 rather than 1.9 or are getting error messages about requiring rubygems run:
gem install rubygems-update

Now install the barryk/github-gem :
curl -O http://github.com/barryk/github-gem/raw/master/github-kb-0.4.2.gem gem install github-kb-0.4.2.gem

You can run gem install as root or as your local user. If run as a user then you must modify your path to include github. The gem command will tell you what needs to be added, put something like:

export PATH=$PATH:~/.gem/ruby/1.9.1/bin in your ~/.bashrc file

Now you have the github-gem installed but must config it. On the Account Settings page you should see an API Token, copy this and run:
github config YourGithubUsername JustATest ThatLongAPIToken

Now you can begin forking a repo. This can be done via the github.com interface or from the command line. We’ll use the cli and fork TeslaCat’s JustATest repo
github fork TeslaCat/JustATest

Now you have your own fork and can begin making changes. All changes should be done in a branch. Your current branch is “master” which in this workflow we will reserve for merges only. Create a new branch with a command like:
git checkout -b MyNewBranch
Generally the branch should be named after the feature or bug you are working on.
Now you can make changes to the files. When you are pleased with your changes you stage these files with:
git add filename.c
Staging changes means they will be included in your next commit. After one or more stages, commit them to your local branch with:
git commit
Be sure to include a descriptive commit message

You can continue working and adding more commits. Note that this is only taking place on your local machine. To publish these changes you can push your branch to github:
github push-branch

After pushing a branch you probably want someone else to accept it. Either through the www.github.com pull-request interface or from the CLI initiate a pull-request:
github pull-request TeslaCat
Not you can send a pull-request to any user, it doesn’t have to be Tesla.

That’s it for submitting changes.

Now for receiving, let’s say you received a pull-request, or you discovered a branch that interests you. You can review this branch before merging by running:
github review barryk/AwesomeBranch
Now you have a checkout and can test the code or view the diff against your master with:
git diff master

Finally you can either fail it:
github review-fail
Which will let you enter a message on why you failed it
Or you can pass it, into your master
github review-pass