Merge pull request #170 from mvdebolskiy/updt-noresm-to-5.3.084

Updt noresm to ESCOMP/ctsm5.3.085

Author: mvdebolskiy

.git-blame-ignore-revs

@@ -64,3 +64,14 @@ e8fc526e0d7818d45f171488c78392c4ff63902a
 cdf40d265cc82775607a1bf25f5f527bacc97405
 251e389b361ba673b508e07d04ddcc06b2681989
 8ec50135eca1b99c8b903ecdaa1bd436644688bd
+3b7a2876933263f8986e4069f5d23bd45635756f
+3dd489af7ebe06566e2c6a1c7ade18550f1eb4ba
+742cfa606039ab89602fde5fef46458516f56fd4
+4ad46f46de7dde753b4653c15f05326f55116b73
+75db098206b064b8b7b2a0604d3f0bf8fdb950cc
+84609494b54ea9732f64add43b2f1dd035632b4c
+7eb17f3ef0b9829fb55e0e3d7f02e157b0e41cfb
+62d7711506a0fb9a3ad138ceceffbac1b79a6caa
+49ad0f7ebe0b07459abc00a5c33c55a646f1e7e0
+ac03492012837799b7111607188acff9f739044a
+d858665d799690d73b56bcb961684382551193f4

.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 documentation issue is this?
+- [ ] Something is missing.
+- [ ] Something is (or might be) incorrect or outdated.
+- [ ] Something is confusing.
+- [ ] Something is broken.
+
+### What part(s) of the documentation does this concern?
+- [ ] [Technical Note](https://escomp.github.io/CTSM/tech_note/index.html) (science and design of the model)
+- [ ] [User's Guide](https://escomp.github.io/CTSM/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

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -e
+
+# Check that clm6* compset aliases return CLM6* longnames
+
+# Change to top level of clone
+cd "$(git rev-parse --show-toplevel)"
+
+# Check that query_config can run without error
+cime/scripts/query_config --compsets 1>/dev/null
+
+# Find bad compsets
+OLD_IFS=$IFS
+IFS='\n'
+set +e
+# Relies on case sensitivity here: Alias should have Clm6 and longname should have CLM6
+bad_compsets="$(cime/scripts/query_config --compsets | sort | uniq | grep Clm6 | grep -v CLM6)"
+set -e
+if [[ "${bad_compsets}" != "" ]]; then
+    echo "One or more compsets with Clm6 alias but not CLM6 longname:" >&2
+    echo $bad_compsets  >&2
+    exit 1
+fi
+
+exit 0

.github/workflows/check-clm6-aliases.sh

@@ -0,0 +1,40 @@
+name: Check that clm6* compset aliases return CLM6* longnames
+# Only check files in our repo that AREN'T in submodules
+# Use a Python command to check each file because xmllint isn't available on GH runners
+
+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:
+      - '.github/workflows/check-clm6-aliases.sh'
+      - 'cime/**'
+      - 'cime_config/config_compsets.xml'
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    paths:
+      - '.github/workflows/check-clm6-aliases.sh'
+      - 'cime/**'
+      - 'cime_config/config_compsets.xml'
+
+  workflow_dispatch:
+
+jobs:
+  check-clm6-aliases:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Checkout submodules
+        run: |
+          bin/git-fleximod update
+          
+      - name: Install xmllint for CIME
+        run: |
+          sudo apt-get update && sudo apt-get install --no-install-recommends -y libxml2-utils
+
+      - name: Check aliases
+        run: |
+          .github/workflows/check-clm6-aliases.sh

.github/workflows/check-clm6-aliases.yml

@@ -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:
@@ -42,7 +42,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
 
       # 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
@@ -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,12 +71,14 @@ 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).
       - name: Generate artifact attestation
-        uses: actions/attest-build-provenance@v2
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be  # v2
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           subject-digest: ${{ steps.push.outputs.digest }}

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

@@ -1,25 +1,29 @@
 # 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
+name: Build and test ctsm-docs container
 
-# 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/**'
-      - '.github/workflows/docker-image-ctsm-docs-build.yml'
-      - '.github/workflows/docker-image-build-common.yml'
+      - '!doc/ctsm-docs_container/README.md'
+      - '.github/workflows/docker-image-common.yml'
 
   pull_request:
+    # Run on pull requests that change the listed files
     paths:
       - 'doc/ctsm-docs_container/**'
-      - '.github/workflows/docker-image-ctsm-docs-build.yml'
-      - '.github/workflows/docker-image-build-common.yml'
+      - '!doc/ctsm-docs_container/README.md'
+      - '.github/workflows/docker-image-common.yml'
 
   workflow_dispatch:
 
 # There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
 jobs:
   build-image-and-test-docs:
+    if: ${{ ! github.repository == 'ESCOMP/CTSM' }}
     name: Build image and test docs
     uses: ./.github/workflows/docker-image-common.yml
     secrets: inherit

.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,19 +26,23 @@ 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
-      packages: write
-      attestations: write
-      id-token: write
 
     steps:
 
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      # 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
@@ -52,7 +57,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.
@@ -68,16 +73,25 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
 
-      # Try building our docs using the new container
-      - name: Checkout doc-builder external
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
         run: |
-          bin/git-fleximod update doc-builder
+          bin/git-fleximod update -o
+
       - 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
-      - name: Build docs using container
+          echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | head -n 1 | cut -d',' -f1)" >> $GITHUB_ENV
+
+      - name: Build docs using Docker (Podman has trouble on GitHub runners)
         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@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - 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