Branch, Tag, and Version name conventions

Owned by Robert Jacob
Last updated: Apr 20, 2023
5 min read

Background

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

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

For background, see discussions at /wiki/spaces/SE/pages/3244039 page,  /wiki/spaces/SE/pages/4718815, /wiki/spaces/SE/pages/5407073, and Council /wiki/spaces/CNCL/pages/18940320.

Development  (aka Topic or Feature) Branch Names

What: A Development or "Topic" or "Feature" branch is made for any code changes needed for E3SM.  This can be new development, bug fixes, config changes or maintenance updates.

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

Convention:  E3SM branch names on E3SM-Project/E3SM must have the form:

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

Branches on a developer's personal E3SM fork do not need to start with <Github username> because this is clear from the fork name:

<source code area or component>/<feature-description>
  • Use lower-case for everything.  Even your username.
  • 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 E3SM IG needs one person to act as point-of-contact to answer questions about the branch and take requests for merging.
    • This is why github usernames should be close to the your real name.
    • Only needed for branches directly on E3SM-Project/E3SM 
  • Group leads may make additional conventions for <source code area or component> and <feature-description>.

Examples

maltrud/machinefiles/mustang
singhbalwinder/atm/polar-mods 
tangq/cam/rrm  
douglasjacobsen/clm/import-v4.5.72

Permanent Branch Names: master, next, maint-x.y

What:  The E3SM 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. Also called an "Integration" branch.  NEVER DO DEVELOPMENT OR SIMULATIONS FROM next.

maint-x.y:  A branch started when a vX.Y release (internal or external) is made and used to provide updates and bug fixes for that release.  A.k.a "release branch".  After the maintenance branch is made, master can proceed to the next version.

Examples:

maint-1.0 - contains updates and bug fixes to v1.0

maint-1.1 - contains updates and bug fixes to v1.1

maint-2.0 - contains updates and bug fixes to v2.0

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

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

Tag Names on master and maint-x.y

Who:  Only integrators can create release tags of these branches.  It is OK for users to make archival tags on master.

What: E3SM will not tag every single merge into the E3SM master.  E3SM will use tags on master to mark significant development stages, and may coincide with versions where the simulations groups devote significant resources to evaluate climate or code performance. 

The recommended method for users to mark specific points on the git master branch is for them to create a topic branch or fork.   

For current and upcoming tags on master and maint-x.y see Existing and Planned Tags and Branches

Tag Names on feature branches:  Archive Tags

Who:  Users and teams can tag their development branches in certain cases.

What: Tags can be used to archive versions of the code. This is the case where 

  1. exploratory runs were made (for climate or performance) and that commit was not already tagged on a permanent branch (see below).
  2. where speculative code development was performed, not merged into master, but needs to be retained
  3. Some journals requires the precise code used in the published simulations be available publicly.  Simulations made during the development process may be using code that doesn't have an official tag like "acmev1-beta01", and one can create an archive tag to identify this version.  Archival tags will publicly accessible in E3SM public releases.  

(See /wiki/spaces/SE/pages/4718815 for discussion that articulated this use case.

Naming:

archive/<User or Group Name>/<description>

Note that once a commit has been tagged, it will be preserved even if the branch it's on gets deleted. We recommend that unused branches be deleted and we can rely on the archive tag to keep needed commits reachable.  Component teams may want to adopt a consistent versioning system within their tag namespace, such as

  • archive/cam/5.3.1
  • archive/cam/5.3.2
  • archive/cam/5.3.3

E3SM Version Names

E3SM will generally follow Semantic Versions 2.0.0  http://semver.org/spec/v2.0.0.html

In general, versions are labeled vMAJOR.MINOR.PATCH

First release of major versions are labeled as "vX.0.0".

First release of minor versions will be labeled as "vX.Y.0" with Y>0. (Note: Y is not limited to 1-9, so we can have v1.27.0 before v2.0.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.

We increment the numbers as follows:

  1. MAJOR version when significant new science capabilities are added and old ones possibly deleted.
  2. MINOR version when E3SM adds minor new science functionality in a backwards-compatible manner, and
  3. PATCH version when E3SM makes backwards-compatible bug fixes that do not change answers for supported cases.

alpha, beta, rc 

Prior to a vX.0 (X >1), E3SM may add alpha, beta and rc lables to versions as follows:

alpha = after all new features have been integrated.  This version is run for a decade or more to look for instabilities not detected by short running development/integration testing.  The first alpha tag is made after all the features from the feature freeze have been integrated to master.  Additional alpha tags are made as needed.

beta = after alpha.  Versions used for coupled tuning.   The first beta tag is made after the coupled simulation group says alpha testing is finished.

rc = release candidate.  Near-final version. Checked for documentation, portability.   Typically, the "rc" versions and released versions are nearly identical.  We don't always use "rc" tags and will go from beta to a regular release tag.

Tag sequence before v1.0 may look like: v0.1, v0.2, .... v0.14, v0.15.....v1.0.0-alpha.1, v1.0.0-alpha.2, ...., v1.0.0-beta.1,  v1.0.0-beta.2, ..., v1.0.0-rc.1,v1.0.0-rc.2, ...., v1.0.0

Figure:  Tags and development graph

The figure below illustrates the relationship between tag names and code development history.

Every circle represents a commit of some code.