Merge pull request #3154 from samsrabin/b4b-dev-merge-20250524

Merge b4b-dev 2025-05-24

Author: samsrabin

.git-blame-ignore-revs

@@ -64,3 +64,6 @@ e8fc526e0d7818d45f171488c78392c4ff63902a
 cdf40d265cc82775607a1bf25f5f527bacc97405
 251e389b361ba673b508e07d04ddcc06b2681989
 8ec50135eca1b99c8b903ecdaa1bd436644688bd
+3b7a2876933263f8986e4069f5d23bd45635756f
+3dd489af7ebe06566e2c6a1c7ade18550f1eb4ba
+742cfa606039ab89602fde5fef46458516f56fd4

.github/ISSUE_TEMPLATE/03_documentation.md

@@ -0,0 +1,24 @@
+---
+name: Documentation
+about: Something should be added to or fixed in the documentation
+
+---
+
+
+### What sort(s) of issue is this?
+- [ ] Something is missing.
+- [ ] Something is (or might be) incorrect.
+- [ ] Something is confusing.
+- [ ] Something is broken.
+
+### What part(s) of the documentation does this concern?
+- [ ] [Technical Note](https://escomp.github.io/ctsm-docs/versions/master/html/tech_note/index.html) (science and design of the model)
+- [ ] [User's Guide](https://escomp.github.io/ctsm-docs/versions/master/html/users_guide/index.html) (using the model and related tools)
+- [ ] Somewhere else (e.g., README file, tool help text, or code comment): _Please specify_
+- [ ] I don't know
+
+### Describe the issue
+A clear and concise description of what is missing or wrong.
+
+### Additional context (optional)
+Add any other context or screenshots about the issue here.

.github/ISSUE_TEMPLATE/03_other.md

@@ -0,0 +1,7 @@
+---
+name: Other
+about: Other issues (enhancement, cleanup, etc.)
+
+---
+
+

.github/ISSUE_TEMPLATE/04_other.md

@@ -2,12 +2,12 @@
 name: Build and publish ctsm-docs Docker image
 
 on:
-  # Run this whenever something gets pushed to master
+  # Run this whenever a change to certain files gets pushed to master
   push:
     branches: ['master']
     paths:
-      - 'doc/ctsm-docs_container/Dockerfile'
-      - 'doc/ctsm-docs_container/requirements.txt'
+      - 'doc/ctsm-docs_container/**'
+      - '!doc/ctsm-docs_container/README.md'
 
   # Run this whenever it's manually called
   workflow_dispatch:
@@ -31,7 +31,7 @@ jobs:
     env:
       REGISTRY: ${{ needs.build-image-and-test-docs.outputs.REGISTRY }}
       IMAGE_NAME: ${{ needs.build-image-and-test-docs.outputs.IMAGE_NAME }}
-      IMAGE_TAG: ${{ needs.build-image-and-test-docs.outputs.image_tag }}
+      VERSION_TAG: ${{ needs.build-image-and-test-docs.outputs.version_tag }}
 
     # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
     permissions:
@@ -61,6 +61,7 @@ jobs:
       # This step uses the `docker/build-push-action` action to build the image, based on the ctsm-docs `Dockerfile`.
       # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.
       # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
+      # Note that we should avoid relying on the "latest" tag for anything, but it's good practice to have one.
       # v6.15.0
       - name: Push Docker image
         id: push
@@ -70,7 +71,9 @@ jobs:
           platforms: linux/amd64,linux/arm64
           push: true
           load: false
-          tags: ${{ env.IMAGE_TAG }}
+          tags: |
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+            ${{ env.VERSION_TAG }}
           labels: ""
 
       # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see [Using artifact attestations to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).

.github/workflows/docker-image-build-publish.yml

@@ -1,19 +1,24 @@
 # Modified from https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#publishing-a-package-using-an-action (last accessed 2025-05-09)
 name: Test building ctsm-docs Docker image and using it to build the docs
 
-# Configures this workflow to run every time a change in the Docker container setup is pushed to the master branch
+# Configures this workflow to run every time a change in the Docker container setup is pushed or included in a PR
 on:
   push:
+    # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
+    branches: ['*']
     paths:
       - 'doc/ctsm-docs_container/**'
+      - '!doc/ctsm-docs_container/README.md'
       - '.github/workflows/docker-image-ctsm-docs-build.yml'
-      - '.github/workflows/docker-image-build-common.yml'
+      - '.github/workflows/docker-image-common.yml'
 
   pull_request:
+    # Run on pull requests that change the listed files
     paths:
       - 'doc/ctsm-docs_container/**'
+      - '!doc/ctsm-docs_container/README.md'
       - '.github/workflows/docker-image-ctsm-docs-build.yml'
-      - '.github/workflows/docker-image-build-common.yml'
+      - '.github/workflows/docker-image-common.yml'
 
   workflow_dispatch:
 

.github/workflows/docker-image-build.yml

@@ -9,14 +9,15 @@ on:
       IMAGE_NAME:
         description: "Docker image name"
         value: ${{ jobs.build-image-and-test-docs.outputs.IMAGE_NAME }}
-      image_tag:
-        description: "First image tag"
-        value: ${{ jobs.build-image-and-test-docs.outputs.image_tag }}
+      version_tag:
+        description: "Version tag from Dockerfile"
+        value: ${{ jobs.check-version.outputs.VERSION_TAG }}
 
-# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
+# Defines custom environment variables for the workflow.
 env:
     REGISTRY: ghcr.io
-    IMAGE_NAME: ${{ github.repository }}/ctsm-docs
+    IMAGE_BASENAME: ctsm-docs
+    REPO: ${{ github.repository }}
 
 # There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
 jobs:
@@ -25,8 +26,7 @@ jobs:
     # Variables that might be needed by the calling workflow
     outputs:
       REGISTRY: ${{ env.REGISTRY }}
-      IMAGE_NAME: ${{ env.IMAGE_NAME }}
-      image_tag: ${{ steps.set-image-tag.outputs.IMAGE_TAG }}
+      IMAGE_NAME: ${{ steps.set-image-name.outputs.IMAGE_NAME }}
     # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
     permissions:
       contents: read
@@ -39,6 +39,14 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      # Ensure that the repository part of IMAGE_NAME is lowercase. This is needed because Docker requires image names to be entirely lowercase. Note that the *image name* part, set as IMAGE_BASENAME in the env block above, is *not* converted. This will cause the check-version job to fail if the IMAGE_BASENAME contains capitals. We don't want to silently fix that here; rather, we require the user to specify a lowercase IMAGE_BASENAME.
+      - name: Get image name with lowercase repo
+        id: set-image-name
+        run: |
+          lowercase_repo=$(echo $REPO | tr '[:upper:]' '[:lower:]')
+          echo "IMAGE_NAME=${lowercase_repo}/${IMAGE_BASENAME}" >> $GITHUB_ENV
+          echo "IMAGE_NAME=${lowercase_repo}/${IMAGE_BASENAME}" >> $GITHUB_OUTPUT
+
       # Uses the `docker/login-action` action to log in to the Container registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
       - name: Log in to the Container registry
         uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
@@ -52,7 +60,7 @@ jobs:
         id: meta
         uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
         with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          images: ${{ env.REGISTRY }}/${{ steps.set-image-name.outputs.IMAGE_NAME }}
 
       # This step uses the `docker/build-push-action` action to build the image, based on the ctsm-docs `Dockerfile`.
       # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.
@@ -75,9 +83,16 @@ jobs:
       - name: Set image tag for docs build
         id: set-image-tag
         run: |
-          echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | cut -d',' -f1)" >> $GITHUB_ENV
-          echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | cut -d',' -f1)" >> $GITHUB_OUTPUT
+          echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | head -n 1 | cut -d',' -f1)" >> $GITHUB_ENV
       - name: Build docs using container
         id: build-docs
         run: |
           cd doc && ./build_docs -b ${PWD}/_build -c -d -i $IMAGE_TAG
+
+
+  check-version:
+    needs: build-image-and-test-docs
+    uses: ./.github/workflows/docker-image-get-version.yml
+    with:
+      registry: ${{ needs.build-image-and-test-docs.outputs.REGISTRY }}
+      image_name: ${{ needs.build-image-and-test-docs.outputs.IMAGE_NAME }}

.github/workflows/docker-image-common.yml

@@ -0,0 +1,72 @@
+name: Get and check version specified in a Dockerfile
+
+on:
+  workflow_call:
+    inputs:
+      registry:
+        required: true  # Require any workflows calling this one to provide input
+        type: string
+        default: 'ghcr.io'  # Provide default so this workflow works standalone too
+      image_name:
+        required: true  # Require any workflows calling this one to provide input
+        type: string
+        default: 'escomp/ctsm/ctsm-docs'  # Provide default so this workflow works standalone too
+    outputs:
+      VERSION_TAG:
+        description: "Tag to be pushed to container registry"
+        value: ${{ jobs.get-check-version.outputs.VERSION_TAG }}
+  workflow_dispatch:
+    inputs:
+      registry:
+        description: 'Container registry'
+        required: false
+        type: string
+        default: 'ghcr.io'
+      image_name:
+        description: 'Image name'
+        required: false
+        type: string
+        default: 'escomp/ctsm/ctsm-docs'
+
+# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
+jobs:
+  get-check-version:
+    name: Get version number from Dockerfile and check it
+    runs-on: ubuntu-latest
+    outputs:
+      VERSION_TAG: ${{ steps.get-check-version.outputs.version_tag }}
+    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
+    permissions:
+      contents: read
+      packages: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Get version number from Dockerfile and check it
+        id: get-check-version
+        run: |
+          set -e
+          set -o pipefail
+          set -u
+          VERSION="$(doc/ctsm-docs_container/get_version.sh)"
+          VERSION_TAG="${{ inputs.registry }}/${{ inputs.image_name }}:${VERSION}"
+
+          # Store the manifest inspect result and output
+          set +e
+          INSPECT_RESULT="$(docker manifest inspect "$VERSION_TAG" 2>&1)"
+          INSPECT_STATUS=$?
+          set -e
+
+          if [[ "${INSPECT_RESULT}" == *"schemaVersion"* ]]; then
+            echo "Tag $VERSION_TAG already exists!" >&2
+            exit 123
+          elif [[ "${INSPECT_RESULT}" != "manifest unknown" ]]; then
+            # "manifest unknown" means the tag doesn't exist, which is what we want
+            echo -e "Error checking manifest for $VERSION_TAG:\n${INSPECT_RESULT}" >&2
+            exit $INSPECT_STATUS
+          fi
+
+          echo "Setting version_tag to $VERSION_TAG"
+          echo "version_tag=$VERSION_TAG" >> $GITHUB_OUTPUT

.github/workflows/docker-image-get-version.yml

@@ -2,10 +2,13 @@ name: Test building docs with ctsm_pylib
 
 on:
   push:
+    # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
+    branches: ['*']
     paths:
       - 'python/conda_env_ctsm_py.txt'
 
   pull_request:
+    # Run on pull requests that change the listed files
     paths:
       - 'python/conda_env_ctsm_py.txt'
 

.github/workflows/docs-ctsm_pylib.yml

@@ -3,12 +3,21 @@ name: Test building docs when they're updated
 
 on:
   push:
+    # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
+    branches: ['*']
     paths:
       - 'doc/**'
+      - '!doc/*ChangeLog*'
+      - '!doc/*ChangeSum*'
+      - '!doc/UpdateChangelog.pl'
 
   pull_request:
+    # Run on pull requests that change the listed files
     paths:
       - 'doc/**'
+      - '!doc/*ChangeLog*'
+      - '!doc/*ChangeSum*'
+      - '!doc/UpdateChangelog.pl'
 
   workflow_dispatch: