Collaboration Workflow

Example Hello World github usage

Bar will update hello.py, and Foo will code review it.

1. issue created with objective
   • e.g. Foo opens the HelloWorld github repo page, clicks Issues, and then New Issue
2. issue assignee creates feature branch or fork from master (branch preferred)
   • e.g. Bar creates a branch
   • 
3. objective completed in branch
   • clone the branch

$ git clone -b greet-user https://github.com/FooBar11112222/HelloWorld.git

* develop code, pushing regularly to branch

$ git commit -a -m "Added name prompt, for #1"
$ git push

    * note that if you [mention](https://github.com/blog/957-introducing-issue-mentions) the issue number followed by a # in the commit message like above, a comment will automatically be added to the issue with a link to the commit
* add test plan, verify test plan passing
* ![TestPlanAdded.png](http://jdimatteo.github.io/images/TestPlanAdded.png)
* ideally also add automated test so that it will continue to automatically be tested in the future (e.g. a diff test, like [the Bam_Liquidator_Bin_Counter_Test Jenkins test](http://tod.dfci.harvard.edu/jenkins/job/Bam_Liquidator_Bin_Counter_Test/), which runs automatically on every commit, and verifies that the counts have not changed since a prior run's calculated counts for a specific bam file)

4. merge request created
   • click the green "Compare & review" button
   • 
   • click the "Click to create a pull request for this comparison" header button
   • 
   • Update the pull request as you see fit, then click the "Send pull request" button
   • 
5. peer code review (code reviewer or other peer also verifies testing passes, e.g. by adding comment "test passes")
6. assignee responds to peer comments (usually with further commits, and re-syncing with master if significant time elapsing), repeat prior step
7. assignee merges branch with master when code reviewer gives the go ahead (e.g. with a comment "merge it")
8. Jenkins GUI wrapper jobs (and anything else using master) automatically uses updated master

Objectives

• stable and usable master branch
• code review and testing so that master branch code is understandable and of high quality
• someone other than original developer verifying test plan passes
• as simple a a process as could possibly work (with the understanding that it can be made more complicated as needed)

Prior Drafts

• initial diagram, more complicated than current draft, with stable master but named release branch for a dedicated testing phase:

References

• http://scottchacon.com/2011/08/31/github-flow.html
• https://github.com/blog/1557-github-flow-in-the-browser
• https://help.github.com/articles/using-pull-requests
• https://github.com/blog/1377-create-and-delete-branches
• https://github.com/blog/957-introducing-issue-mentions
• https://help.github.com/articles/how-do-i-set-up-a-team
• http://nvie.com/posts/a-successful-git-branching-model/
• Version Control with Git