Branch/Merge Notes

git_guide.md

Flowsim Branch Strategy

We will have two permanent branches in the repository: develop, and master. Develop is the branch were we will manage our development train of code. Master will represent a set of clean releases that have been publicly released and running on flowsim.flowgrammable.org. We will use three types of temporary branches to facilitate new feature development, release candidate bug fixes, and hotfixes on public releases from master. This process mimics a typical git workflow. Temporary branches will either be deleted or merged into a permanent branch using a pull-request.

Branch Descriptions

Branch Name	Lifetime	Source	Target	Description
master	permanent	n/a	n/a	publicly released code
develop	permanent	n/a	n/a	development code train
feature-	temporary	develop	develop	enahancement development
release-	temporary	develop	master, develop	candidate bug development
hotfix-	temporary	master	master, develop	public bug development

Motivation

• Cleanly separate development activity from released code
• Provide isolation for new feature development and testing
• Provide isolation for bug patches on released code
• Provide isolation for release planning
• Provide framework for a larger distributed development group

Branch Procedures

Bug Fix - branches: develop, release-

1. Change to the develop or release-* branch
   • git checkout <develop | release-<X>>
2. Ensure you are at the top of the branch
   • git pull
3. Fix the issue, commit, and push your results
   • make changes until you are satisfied
   • git commit -a
   • git push

New Feature - adding a new capability

1. Create the feature branch, sync with origin
   • git checkout develop
   • git checkout -b feature-<X>
   • git push --set-upstream origin feature-<X>
2. Develop the new feature
   • make changes until you are satisfied
   • git commit -a
   • git push
3. Generate pull-request
   • initiate a pull-request with the develop branch (through github.com UI or CLI)
   • Reviewer will submit issues (goto 2.) or accept (goto 4.)
4. Reviewer acceptance/reject (github supports a UI accept/reject/discuss variant)
   • git checkout -b feature-<X> origin/feature-<X>
   • git merge develop
   • feature is acceptable
     • git checkout develop
     • git merge feature-<X>
     • git push
     • git branch -d feature-<X>
     • git push origin --delete feature-<X>

Release Candidate - establishing a release candidate from develop

1. Create the release branch
   • git checkout develop
   • git checkout -b release-<release #>
   • git push --set-upstream origin release-<release #>
2. Fix any release candidate bugs
   • fix all bugs in release-<release #> branch
   • no more merge from develop

Release - releasing a release candidate

1. Generate pull-request
   • initiate a pull-request master -> release-<release #>
   • Reviewer will reject or accept
2. Reviewer acceptance/reject (github supports a UI accept/reject/discuss variant)
   • git checkout -b release-<release #> origin/release-<release #>
   • git merge master
   • Release - feature is acceptable
     • git checkout master
     • git merge release-<release #>
     • git push
   • Don't lose any fixes
     • git checkout develop
     • git push
   • Cleanup - feature release is temporary
     • git branch -d release-<release #>
     • git push origin --delete release-<release #>

Git Commands

Command	Description
git branch	list local branches
git branch -a	list local and remote branches
git checkout -b	create local branch from HEAD
git checkout -b origin/	create local branch from remote branch
git fetch	update local git repo metadata
git checkout	change HEAD to the branch
git merge	merge branch with HEAD
git branch -d	delete a local branch
git push origin --delete	delete a remote branch
git remote prune origin	clean up remote branch cache
git tag -a -m ''	tag the current HEAD of branch
git push --tags origin	sync local tags with origin

HEAD

The HEAD is your git repo pointer. It always points to what is active in your environment. When you perform a fresh clone or pull, it points to the last change made in the repo. Many of the git commands just manipulate this pointer. Moving between branches invovles changing what HEAD points to (last change of target branch).