Tag and Release Protocol

All pull request merges should be tagged after the fact to identify which particular files have been updated and to facilitate automated builds on dockerhub. See the Dockerhub Repository Integration wikipage for more information on automated builds.

Tag Versioning Format

Tags should follow this general format:

<prefix>-v.<x>.<y>.<z>

where:

• prefix: See Prefixes subsection below
• x: major stable update
• y: feature update
• z: bug fix update

For example: gcc650-v.1.0.0 would the first major stable release for the gcc 6.50 baseos image.

Note that tagging is somewhat subjective and updates should probably be discussed with other members of the dev team to come to a consensus on the update number.

Note that it is not necessary to push a <prefix>-latest tag. Dockerhub internal autobuild hooks have been enable to post process the last build with a latest tag without git intervention. See the Dockerhub documentation on custom build phase hooks and PR#13 for more information.

Prefixes

Use the following prefixes to identify the specific dockerfile that has been updated in the most recent pull request. Note however that a given pull request may have multiple tags associated with it (e.g. a PR updates the gcc650 based-dockerfile and the ctsm-based dockerfile at the same time).

• gccxxx: Debian-based GCC dockerhub base image version xxx
• centosxxx: Centos dockerhub base image version xxx
• ctsm: Image with CTSM host land model installed
• cesm: Image with CESM host land model installed
• e3sm: Image with E3SM host land model installed
• fates: Image with FATES model installed

Note that prefixes can and should 'stack' to denote the various combinations of images that depend on other images. For example fates-ctsm-gcc650-v.0.2.0 would be the FATES dockerfile update using the CTSM docker image that is itself based on the GCC 6.50 baseos image.

Note that the above list is not meant to be limiting and can be expended as needed by developer consensus. At the time of this writing not all of the prefixes have been yet implemented.

Steps to tag a PR

1. After merging PR, pull in latest changes and tags to your local master branch.

   • git checkout <ngeet/master branch>
   • git pull <ngeet/remote repo name>

   Note that if you have your repo setup to track both the NGEET and your personal remote, you may have a matching tag already created from testing the autobuild on your personal dockerhub account. It is recommended that your personal autobuild tests use a tag variation to avoid this. This will help keep the tags on your local repo clear and reduce the likelihood of pushing the wrong tag to the wrong remote.

2. Verify that you have the latest tag available by comparing github release/tags page and using:

   • git tag

3. Create a new annotated tag for the currently checkout ngeet/master branch. Annotated tags have been suggested by CSEG (for FATES) as they are full-featured objects in git and have many features. Make sure to include a descriptive message. It is recommended that you include the major programs and their version numbers that are included in the dockerfile build instructions (e.g. "OPENMPI_VERSION=2.1.5, ...")

   • git tag -a <prefix-v.x.x.x> -m "*put message here*"

4. Push the tag to ngeet/docker-fates-tutorial remote:

   • git push <ngeet/remote repo name> <prefix-v.x.x.x>

   Theoretically you could push multiple tags at one time.

5. Go to the release/tags page and check that the tag is there.

Releases

Releases are created when the development team comes to an agreement that a set of recent updates constitutes a major stable update for the whole of the repo (i.e. for all dockerfiles). As of this writing, they don't have a purpose outside of helping to chronologically mark these milestones.

Release steps

1. Create a release based on the tag. Click the ellipses on the far right and select 'create release'.

2. It's ok to just copy/paste the tag message and use that as the release message. If this is a major changes that should be considered the latest 'stable', leave the 'pre-release' unchecked. Check the 'pre-release' box if the change is an upgrade that has not been extensively used by users yet.