How to

Technical instructions

• git. there are many git instruction online e.g., https://www.atlassian.com/git/glossary#commands

how to tag

version name convention

Name convention: try following CTSM: https://github.com/ESCOMP/CTSM/wiki/Tag-naming-conventions

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

Example

• BRANCHNAME.nXX_vX.X.X
• BRANCHNAME.nXX_BASELINETAG

where:

• BRANCHNAME 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:
    • release
• This name should NOT contain any of these characters (which are used as separators in the full tag name):
  • .
  • _
• nXX 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-5.0.15 or use vX.X.X format

Example: cesm-coupling.n01_v2.0.1

release is for more stable more highly tested configurations. For CTSM we only release public versions that we tag as "release-*". You can also tag a release as "pre-release" which we do for release tags that aren't in a CESM release version.

git commands to tag the commit with version name (tag_name) and annotation (-a option)

git checkout <branch_name>
git tag -a <tag_name>
git push <remote_name> <tag_name>

e.g., for serial code (main branch)

At local git repository (in terminal),

git fetch ESCOMP
git checkout main
git rebase ESCOMP/main 
git tag -a v1.2.2
git push ESCOMP v1.2.2

For tagging, you may push it to the upstream remote repository(so here it is ESCOMP/mizuroute.git).

Note on annotated tag

The "-a" means an annotated tag that has you add the description of what you are doing. This is recommended for tags. Without -a flag, tag will be "unannotated" or "lightweight" tags. Annotated tags are better because they also do a commit for them. So you see a hash for the specific commit in the commit log for the tag, and not just a pointer to the commit the tag points to. Doing a "git describe" also shows the annotated tag that it's closest to by default. You can add arguments to see it for lightweight tags, but you have to add it.

Tracking the changes

Use this to keep track of what has been done from the previous tag.

This page is adapted from https://github.com/ESMCI/cime/issues/2817