Tag naming conventions

Tag naming conventions

• Development Tags
• Release Tags
• Alpha Tags
• Branch Tags

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.

Alpha Branches and tags

Sometimes before major development series tags can be done, there are changes to inputdata tools that need to happen in front of the actual development tag series. Usually, this is only done for updates to the mksurfdata tool. But, possibly it could apply to other inputdata tools or for other reasons. In this case there will be a "alpha" development series proceeding the ctsmX.Y development series.

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. When this branch is made changes to mksurfdata should ONLY go on that branch. The branch should run tools testing for incremental branch tags. Changes that are tied to updated surface datasets can also go on that branch, or on main-dev if they query for the existence of appropriate fields on the fsurdat file. In general though this branch should ONLY be about mksurfdata changes, and changes to mksurfdata should NOT go on main-dev while this branch is in active use. mksurfdata tags normally will NOT update the ChangeLog until the final version comes to ctsm main-dev. The changes for each annotated tag on the branch will go into the tag commit log and they will be assembled into the ChangeLog when the branch comes to the development branch.

Alpha Branches will be named like: ctsmX.Y.NAME

where:

• NAME is the name of the branch, or some designator of the purpose of this tag (usually will be mksurfdata)

Example: ctsm5.2.mksurfdata

Alpha branch tags will be named like: alpha-ctsmX.Y.SNAME.ZZ_ctsmX.B.CCC

where:

• SNAME is the short name of the branch (for example mksrf for the mksurfdata alpha branch)
• ZZ is the incremental tag along the branch
• Note: Y will be the increment of B

Example: alpha-ctsm5.2.mksrf002_ctsm5.1.dev099

Branch tags will include the prefix "alpha", the development version going towards, and "dev" replaced with a shortened descriptor of the branch. So for mksurfdata changes it would be "mksrf". At the end of the name it will also include the exact base development version that the tag is based off of.

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 main-dev 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

Normally branch tags do not update the ChangeLog until and unless it comes to CTSM main-dev.