Tag naming conventions

Tag naming conventions

Conventions in this document

Words in CAPS are placeholders for names.

Capital X, Y and Z stand in for version numbers. XX denotes a two-digit number, YYY a three-digit number, etc. Likewise, Capital A, B, C, and L stand for version numbers for FATES. In that case a single digit is used, but can represent more than a single digit number.

Development tags

Development tags will be named like ctsmX.Y.devZZZ

where:

• X is the major version number, corresponding to a major release
• Y is incremented when there are big changes (e.g., introducing FATES)
• ZZZ is incremented for each tag

Example: ctsm1.0.dev020

We do not add release notes via the GitHub interface for development tags.

Release tags

Release branches will be named like release-NAMEX.Y

where:

• NAME is the name of the model for which the release is being made (typically CTSM or CLM; can be something like CESM for a release of CTSM that is just being made for the sake of a CESM version)
• X.Y is the major and minor version of that model (note that, for a release-cesmX.Y branch, X.Y will give the CESM version for which this release branch applies)

Tags will then be named like release-NAMEX.Y.ZZ

where ZZ is incremented for each tag.

Example: release-clm5.0.15

All tags on the release branch should be labeled as a release on GitHub, with appropriate release notes.

mksurfdata Branches and tags

When there are major developments on the mksurfdata tool that will be brought in for a given CTSM version a branch will be made for those changes to go on. The branch will be named: ctsmX.Y.mksurfdata.

Example: ctsm5.2.mksurfdata

Branch tags will follow the normal branch tagging convention:

Example: branch_tags/ctsm5.2.mksurfdata.n02_ctsm5.1.dev099

FATES main-api tags

Tags of the fates_main_api branch can be made when needed. They document the ctsm version and the FATES API version. The FATES science version can be discovered

FATES tags would be named like BASELINETAG_fates_apiA.B.C(-L)

Where

• BASELINETAG is the baseline tag on a release branch or master that this tag is up-to-date with. For example, this could be release-clm5.0.15 or ctsm1.0.dev020.
• A is the FATES API major version number
• B is the FATES API minor version number
• C is the FATES API bug fix number
• (-L) is optional and is an optional additional letter to be added if an additional means of distinguishing from a previous tag is necessary. For example, this would be used if you had two tags for the same CTSM and FATES API version -- but the FATES science version was different. The other reason would be the CTSM and FATES versions are exactly the same, but some change in the CTSM fates_main_api branch had been made and needed a tag as well.

Example: ctsm1.0.dev105_fates_api14.0.0

Branch tags

Branch tags can be pushed to the ESCOMP/CTSM repo in limited circumstances - e.g., when a given code version is needed for a major set of production runs.

Branch tags will be named like branch_tags/NAME.nXX_BASELINETAG

where:

• NAME is the name of the branch, or some designator of the purpose of this tag.
  • This name should NOT begin with any of these prefixes:
    • ctsm
    • release
  • This name should NOT contain any of these characters (which are used as separators in the full tag name):
    • .
    • _
• XX is the tag version number along this branch; this should just be incremented when a new tag is truly necessary (e.g., not for every commit along this branch)
• BASELINETAG is the baseline tag on a release branch or master that this tag is up-to-date with. For example, this could be release-clm5.0.15 or ctsm1.0.dev020.

Example: branch_tags/ismip6.n02_release-clm5.0.15