Branch, Tag, and Version name conventions

Background

ACME keeps nearly all of its code in a single repository.

To help track development, branch and tag names in the ACME source must follow conventions given here.

For more information, see /wiki/spaces/SE/pages/3244039 discussion.

ACME Version Names

ACME will generally follow Semantic Versions http://semver.org.

Major versions will be labeled as "vX.0".

Minor versions will be labeled as "vX.Y" with Y>0.

Bug-fixes and other changes made to a released version vX.Y will be done on a "maint-X.Y" branch and tagged "vX.Y.Z" with  Z>0.

Major version zero (v0.Y) is for initial development. Anything may change at any time.

Development or Topic Branch Names

What: A Development or "Topic" branch is made for any code changes needed for ACME.  This can be new development, but fixes, merges from CESM, or maintenance updates.

Who: Any ACME developer can create a topic branch.  They can be for development or also to mark a place in the code.

Convention:  ACME branch names will have the form:

<Github username>/<source code area or component>/<feature-description>

• Use lower-case for everything.
• Use hyphens instead of underscores.
• one name for the github username.  
  • This is the person in charge of the branch and not necessarily the only person working on it.
  • The ACME SE team needs one person to act as point-of-contact to answer questions about the branch and take requests for merging.
• Task team leads can and should impose additional conventions for <source code area or component> and <feature-description>.

Examples

maltrud/machinefiles/mustang

singhbalwinder/atm/polar-mods 

tangq/CAM/RRM  

douglasjacobsen/clm/4.5.72

Permanent Branch Names

What:  The ACME source code will have permanent branches used for development and maintenance of the code.

Who:  Only Integrators can change or create new permanent branches.

Convention:

master:   The "trunk" or main branch of the code.  Contains latest stable code.  Always in a releasable state.   Nearly all development should start as a branch from master.

next:   A branch used for merging several topic branches for testing.  Used to test several features at once.   Is destroyed and re-created after the target group of features is merged to master.

maint-x.y:  A branch started when a vX.Y release is made and used to provide updates and bug fixes for that release.  A "release branch".

Examples:

maint-0.0 - contains updates and bug fixes to v0.0

maint-0.1 - contains updates and bug fixes to v0.1

There is no such thing as the "maint-0.0.1" branch.

Developers should avoid using "maint" in their topic branch names.

Tag Names

Who:  Only integrators can create tags.  Users should never tag their development branches.   

What: ACME will not tag every single merge into the ACME master.  ACME will use tags only to mark major and minor releases and bugfix releases.

The recommended method for users to mark specific points on the git master branch is for them to create a topic branch or fork.  These branches are equivalent to subversion style tags used in the CESM.  

Tag name examples

(tags in red have not yet been created as of 19 Aug 2014 )