Skip to content

Tag naming conventions

Jump to bottom
Erik Kluzek edited this page Apr 12, 2024 · 28 revisions

Tag naming conventions

Conventions in this document

Words in CAPS are placeholders for names.

Capital X, Y and Z as well as A and B stand in for version numbers. XX denotes a two-digit number, YYY a three-digit number, etc.

Development tags

Development tags will be named like ctsmX.Y.ZZZ

where:

  • X is the major version number (not changed for dev tags)
  • Y is the minor version number (not changed for dev tags)
  • ZZZ is incremented for each tag

Example: ctsm6.0.020

We do not add release notes via the GitHub interface for development tags. Also the major and minor version numbers are NOT changed for development tags, those can ONLY be changed for a major version update tag.

Standard testing is done for development tags.

Major version update tags

Major versions end a development series of tags with some important or major updates. Incrementing the first digit major version number means a major version with updated simulations, and is usually associated with a CESM major release. When incrementing the major version number the minor version gets reset to zero.

Major version update tags will be named like ctsmX.Y.0

where:

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

Example: ctsm6.0.0

Release testing is done for major version tags. Tags that update the first digit (the major version) will also have a set of scientific vetted simulations that go along with it.

Major version update tags can be labeled as a release on GitHub, with appropriate release notes.

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; 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-ctsm6.0.15

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

Release testing will be done for release tags.

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.A.BBB

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 A The development BASELINETAG that the tag corresponds to is ctsmX.A.BBB

Example: alpha-ctsm5.2.mksrf.002_ctsm5.1.099

Branch tags will include the prefix "alpha", the development version going towards, and "branchname" 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.

Standard or limited testing are done for most alpha tags (until just before it comes in as a major tag update).

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-ctsm6.0.15 or ctsm6.0.020.

Example: branch_tags/ismip7.n02_release-ctsm6.0.15

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

Testing for branch_tags is up to the discretion of the developers of that branch.

Clone this wiki locally