Idiomatic Github development : pull request + fetch remote

 
When getting started with github, its easy to get confused between "forks" and "branches".  In this post we'll go through a simple workflow for pull-request driven development, including the necessary "trick" to keep your personal "forked" repository in sync with the original github repo.

1) Forks are personal - you can "fork" a git hub repository as a way to start developing against an existing repoistory without being coupled to it.  

2) Branches are not necessarily personal : their namespace shared in the same original repository.

Using branches as a commiter on the primary repo:

1) Become a commiter on the repo, write your own branches, and then merge your branches into head.

or 

Contribute by using pull-requests as a non-commiter:

2) FORK the original repo, write code anywhere (including on your "master" branch), and simply issue pull requests upstream. 

The advantage of the 2nd approach : 

1) It doesn't require you to be a registered commiter on a project.

2) It doesn't constrain your workflow (you can write and push changes directly to your master, without worrying about branches).   

3) It naturally enables the convenient github enabled pull user interface as a methodology for incorporating fixes.

In any case, the above methodologies will allow you to develop without effecting the "real" master, and you can use a pull request to "simulate" the insulation provided by branching.

However at some point you will want to pull the changes from the main repo into your fork.  You can do this by adding a 2nd remote to your fork, as follows (see 6 below):

An example:

1) Fork https://github.com/gluster/hadoop-glusterfs

2) git clone https://github.com/jayunit100/hadoop-glusterfs

3) git remote add upstream https://github.com/gluster/hadoop-glusterfs

4) Edit some stuff.

4) git add -A . ; git commit -m "my first commit to my fork" ; git push

5) Issue a pull request

#A few days later, maybe the original repo changes, and we want to pull those changes down:

6) git fetch upstream <-- keep your fork in sync with the original repo.