Mapping to BZ's

If at all possible, contain the entire fix for a BZ to a single
commit, but if more than one commit is needed for the fix, make sure to
list all the commit hashes in the BZ. This is critical so that if the
fix needs to be cherry-picked, all of the commits can be cherry-picked
at the same time and pushed atomically. Also, try to limit commits that
fix a BZ to the bare minimum changes required for the fix. Don't include
other fixes (or parts of other fixes) or reformatting (i.e. whitespace
changes). Such additional inclusions make it harder for someone else to
understand or review the fix. Using local branches can help here. Have
one branch per BZ to help isolate the changes you are making for a
specific fix.

Always Rebase!

99% of the time, when you do a git pull, you should specify --rebase
so that all pending commits are re-applied after the pull. There are two
reasons for this: i) it prevents "merge commits" which clutter the git
history, and ii) when the commits are re-applied, their dates get
updated, which keeps the git history more linear, particularly if a push
is done right after the pull.

You can configure certain branches to always pull with the --rebase flag:

# make 'git pull' on master and release_jon3.x always use rebase
$ git config branch.master.rebase true
$ git config branch.release_jon3.x.rebase true

You can also set up a global option to set the last property for every
new tracked branch:

# setup rebase for every tracking branch
$ git config --global branch.autosetuprebase always

All devs should set the above config options.

Only Push to Current Branch

Configure "git push" to only push to the current branch, rather than to all branches:

git config --global push.default current

Tag Names

Tags are created when important milestones in a development project are achieved; important events may include, but are not limited to:

• alpha's

• beta's

• release candidate

• release

Tag naming follows these conventions for release tags:

• v1.2.3

What remains to be defined is the tagging scheme for important events other than release.

When to Branch

Branch when it is useful:

• when concurrent lines of development occur across releases

• when larger, potentially volatile, changes are created in isolation to prevent breaking master builds

Model

When branching, use a branch-early, merge-often, approach. This helps manage risk; it reduces the likelihood of a large complex merge by amortizing the cost over a series of smaller simpler merges. Merge daily if possible.

Master Branch

Master represents the main line of development; master may be unstable, but with that said developers should strive to never break the builds. Development primarily occurs on master with occasional feature branches feeding larger units of work to it.

Feature Branches

Feature branches, sometimes called story or topic branches, represent larger units of work that, as a unit, may possibly be rolled back atomically. Feature branch histories are squashed prior to commit to master so they may be rolled back from master in the event a feature needs to be removed from a release.

The naming convention for feature branches follows:

• feature/fancywidget

Maintenance Branches

There is no such thing as a release branch; there is only maintenance. Once a release is cut and its tag made, no other activity related to the release occurs unless needed. In other words, maintenance branches are completely unnecessary unless multiple versions face active development; then in this case it exists and serves as an accumulator for accepted patches, a subset of patches that feed into master. The naming convention for maintenance branches follows:

• maintenance/1.2.3

Bug Branches

Bugs may be serviced through patch files or branches, depending upon how complex the fix is. The naming convention for bug branches follows:

• bug/12345

If possible, use patch files instead of branches. N.B. caveat that bug branches are only applicable to a single line of development, a single version.

User Branches

User branches are for random hacking, possibly to showcase new ideas, solicit feedback, or experiment. Where user is the git user name, and topic unambiguously identifies scope of work, user branches follow this naming convention:

• user/topic

There are two ways to incorporate user contributions:

• create a feature branch and cherry pick users changes into it

• cherry pick user changes directly into master if a feature branch of bug branch is not warranted