dev>Version Control Guidelines
We are aiming to simplify our git usage by adopting a simpler workflow (what branches we use and how, and what tags) inspired by that used by the git project itself. We are moving away from the one implemented in git-flow.
We have three long lived branches: enterprise, master and dev. enterprise is for development of the current Enterprise Version and master for the current version, which represent two tradeoffs between stability and features. We don't expect x.y.0 versions to be enterprise versions since they have new untested (in the field) features. There are no licensing difference between the branches, the enterprise branch is called as such because it is used to develop the version distributed with Revolution Enterprise R, which itself contains proprietary components but that has no effect on the code hosted here. Both enterprise and master can receive only bug fixes or documentation improvements. No new feature can go directly into these branches. dev is where the next release is prepared and can receive new features. Changes can go directly into the dev branch if they are minor, otherwise they come from feature branches. Feature branches are dedicated branches where work on new features takes place. Process is there to help us develop better code, not to make fixing a typo an ordeal. In general, if a feature is complex enough that it could be abandoned or delayed by a release, it's worth opening a branch. If its development will leave a package non-functional for a while, breaking other features, that's also a good indication a feature branch is appropriate. There can also be integration branches were complex integrations are attempted before going into dev (if the merger requires collaboration). It'hard to undo things once they are in dev.
Merges take place from feature branches into dev, from dev into to master and from there into enterprise, in this direction and never directly (skipping levels). Hot fixes are applied to enterprise, then merged into master and dev. Sometimes hotfixes won't be needed in enterprise, then the process can start from the next "newer" branch. Also, hotfixing dev is optional, since dev is never distributed and master is merged into dev after a release or whenever deemed appropriate.
tags are applied every time there is a release but can be used for other purposes (like marking a state of the tree where all tests pass on at least one platform). Release tags are applied after a merge from dev into master, after conflicts are resolved and post-merge testing is complete, or after a cycle of bugfixes, again when testing is complete. The syntax of these tags is x.y.z (regular integers, no letters and no leading 0s) according to semantic versioning (semver.org). Other tags or branches need to be named in a way that can not be confused with a release tag, so they can not match this format. (temporary rule, when there is a conflict between a branch name or tag name, just prefix tag- or branch-, this should not happen in the future)
License compatibility needs to be ensured and informal approval from the external repo authors should be sought in advance. Code included from other projects is included at top level with git subtree (subtree is available with the latest git and if you don't have it it shouldn't matter too much unless you want to interact with the subtree's own remote). The remote for the subtree is the original repo. The top level of the repo is above pkg/ so is not included in the package build. The parts that should be included for distribution can be soft linked to from under pkg/, for instance pkg/src/hbase-io is a soft link to hadoopy_hbase.
The best mapping of our branches to an external project's own branches is still work in progress, in the current only example the external project has a single branch master and has no versioning in place so the recommendation is to pull changes from master into dev.