Introduction
The following document is the outcome from an IRC and email thread where RHQ developers discussed branch and tag naming conventions. The topic of branches needs to take into account the overall workflow, and its relationship to tags, hence the three are discussed together here. This is why this document dips its toes also into the waters of workflows.
Tags
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:
What remains to be defined is the tagging scheme for important events other than release.
Branches
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.
Naming Conventions for Branch Types
Following these conventions allows developers to search, using git, for branches following particular patterns:
- git show-branch "maintenance/*"
- git show-branch "bug/*"
- git show-branch "username/*"
Merge histories may also be searched for which bugs have been merged into a branch using this approach.
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:
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:
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:
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:
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
Branch Lifetime
Branches are periodically purged. User branches are purged after six months of inactivity, and feature branches are purged immediately after feature development is done. Bug branches may be kept around longer should the record of change be necessary, but generally are purged after they are merged to master.
References
- IRC Transcripts