Merge branch 'b4b-dev' into ciso_b4b_changes_to_ctsm5.4

Author: ekluzek

.git-blame-ignore-revs

@@ -62,3 +62,16 @@ e8fc526e0d7818d45f171488c78392c4ff63902a
 890b4633c5477dc074f79c69c40d650196337591
 1972cef6bba0d97169b30a53f540d56bcbd97281
 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/black.yml

@@ -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.sh

@@ -0,0 +1,86 @@
+# Based on 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: Build and publish ctsm-docs Docker image
+
+on:
+  # Run this whenever a change to certain files gets pushed to master
+  push:
+    branches: ['master']
+    paths:
+      - 'doc/ctsm-docs_container/**'
+      - '!doc/ctsm-docs_container/README.md'
+
+  # Run this whenever it's manually called
+  workflow_dispatch:
+
+jobs:
+  # This first job checks that the container can be built, and that we can use it to build the docs without error.
+  build-image-and-test-docs:
+    name: Build image and test docs
+    uses: ./.github/workflows/docker-image-common.yml
+    secrets: inherit
+
+  # This second job actually builds and publishes the container.
+  push-and-attest:
+    name: Publish and attest
+    runs-on: ubuntu-latest
+
+    # Wait to run this job until after build-image-and-test-docs. If that job fails, something might be wrong with the container, so don't try this one. (It might also have failed because of something wrong with doc-builder or the documentation.)
+    needs: build-image-and-test-docs
+
+    # Variables output by the build-image-and-test-docs job.
+    env:
+      REGISTRY: ${{ needs.build-image-and-test-docs.outputs.REGISTRY }}
+      IMAGE_NAME: ${{ needs.build-image-and-test-docs.outputs.IMAGE_NAME }}
+      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:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        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
+        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # This step sets up Docker Buildx, which is needed for the multi-platform build in the next step
+      # https://docs.docker.com/build/ci/github-actions/multi-platform/
+      # v3.1.0
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2
+
+      # 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
+        uses: docker/build-push-action@471d1dc4e07e5cdedd4c2171150001c434f0b7a4
+        with:
+          context: doc/ctsm-docs_container
+          platforms: linux/amd64,linux/arm64
+          push: true
+          load: false
+          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@e8998f949152b193b063cb0ec769d69d929409be  # v2
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true
+

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

@@ -0,0 +1,28 @@
+# 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: Build and test ctsm-docs container
+
+# 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-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-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:
+    name: Build image and test docs
+    uses: ./.github/workflows/docker-image-common.yml
+    secrets: inherit

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

@@ -0,0 +1,97 @@
+name: Workflow used by docker-image workflows
+
+on:
+  workflow_call:
+    outputs:
+      REGISTRY:
+        description: "Container registry"
+        value: ${{ jobs.build-image-and-test-docs.outputs.REGISTRY }}
+      IMAGE_NAME:
+        description: "Docker image name"
+        value: ${{ jobs.build-image-and-test-docs.outputs.IMAGE_NAME }}
+      version_tag:
+        description: "Version tag from Dockerfile"
+        value: ${{ jobs.check-version.outputs.VERSION_TAG }}
+
+# Defines custom environment variables for the workflow.
+env:
+    REGISTRY: ghcr.io
+    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:
+  build-image-and-test-docs:
+    runs-on: ubuntu-latest
+    # Variables that might be needed by the calling workflow
+    outputs:
+      REGISTRY: ${{ env.REGISTRY }}
+      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
+
+    steps:
+
+      - name: Checkout repository
+        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
+        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
+        with:
+          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.
+      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
+      # v6.15.0
+      - name: Build Docker image
+        id: build-image
+        uses: docker/build-push-action@471d1dc4e07e5cdedd4c2171150001c434f0b7a4
+        with:
+          context: doc/ctsm-docs_container
+          push: false
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
+        run: |
+          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 }}' | 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 }}