CIME Tag Naming Conventions

Tags of Main Branches

Tags of the main cime branches (master, maint-*, etc.) are named cimeX.Y.Z. These tags roughly follow semantic versioning conventions. See Semantic Versioning 2.0.0 for details.

However, see below ("Tags of Release Branches") for the versioning of branches that are put together to support specific model releases.

Tags of Intermediate Commits on Main Branches

Consider the situation where a new tag is wanted between two existing tags - say, between cime5.8.3 and cime5.8.4. In this case, the new tag should be considered a pre-release tag, and should be named cime5.8.4-1. If additional new tags are needed between cime5.8.3 and cime5.8.4, they will appear like this:

cime5.8.3 < cime5.8.4-1-1 < cime5.8.4-1 < cime5.8.4-2 < cime5.8.4

That is, to introduce a tag before some other tag foo, the new tag will be named foo-1, unless there is already a tag named foo-1, in which case the tag should be named foo-2, etc.

Tags of Release Branches

Sometimes it is necessary to create long lived branches corresponding to releases of external software.
These branch names should reflect the name of the external software package (eg ufs_release_v1.0, cesm2.1, etc.) and tags on the branch should include the branch name: ufs_release_v1.0/cimex.y.z_001. Here, cimex.y.z is the cime version from which this release branch started. We envision that, in most cases, later versions of cime will not be merged into this release branch (though individual commits may be cherry-picked into it), so this starting point is the cime master version that the branch is up-to-date with (or, in git speak, the "merge-base" of the release branch and master). The final component of the tag name (001 in the above example) will be incremented with each new tag on this cime branch.

Tags of Other Branches

Tags of commits that do not appear on one of the main branches should be named like branch_tags/cime5.7.9_a01. This would be a tag of a branch off of cime5.7.9. If another tag is needed that follows on from this one, it would be called branch_tags/cime5.7.9_a02. If, on the other hand, a completely different branch is needed off of cime5.7.9, then it would use a b rather than an a: branch_tags/cime5.7.9_b01.

If a branch starts from an untagged commit on master, use the last tag on master in the branch tag name.