wetlands.n03.ctsm5.4.044: Wetlands update to ctsm5.4.044

.github/ISSUE_TEMPLATE/03_documentation.md

@@ -3,7 +3,7 @@ name: Documentation
 about: Something should be added to or fixed in the documentation
 
 ---
-
+(Please see our [contribution guidelines for documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines).)
 
 ### What sort(s) of documentation issue is this?
 - [ ] Something is missing.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,24 +1,41 @@
+<!-- Please fill this out to the best of your ability when opening your PR! -->
+
+<!-- **NOTE: Be sure to check your coding style against the standard
+(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
+the list of common problems to watch out for
+(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).** -->
+
+
 ### Description of changes
 
+<!-- Description goes here -->
+
 ### Specific notes
 
-Contributors other than yourself, if any:
+**Contributors other than yourself, if any:**
+- (Replace this text and add more list items as needed)
 
-CTSM Issues Fixed (include github issue #):
+**CTSM issues resolved or otherwise addressed, if any:**
+- (Replace this text, including GitHub issue #, and add more list items as needed)
+<!-- Put each issue on its own line, like "Resolves #3986" or "Contributes to #3151". -->
+<!-- "Resolves" is a magic word; see them all at https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue -->
 
-Are answers expected to change (and if so in what way)?
+**If answers are expected to change, describe (delete this line otherwise):**
 
-Any User Interface Changes (namelist or namelist defaults changes)?
+**Any user interface changes (namelist or namelist defaults changes)?**
 
-Does this create a need to change or add documentation? Did you do so?
+**Testing planned or performed, if any:**
+- [ ] (Replace this text and add more list items as needed)
+<!-- (List what testing you did to show your changes worked as expected) -->
 
-Testing performed, if any:
-(List what testing you did to show your changes worked as expected)
-(This can be manual testing or running of the different test suites)
-(Documentation on system testing is here: https://github.com/ESCOMP/ctsm/wiki/System-Testing-Guide)
-(aux_clm on derecho for intel/gnu and izumi for intel/gnu/nag/nvhpc is the standard for tags on master)
 
-**NOTE: Be sure to check your coding style against the standard
-(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
-the list of common problems to watch out for
-(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).**
+
+### Requirements before merge:
+- [ ] I have followed the [CTSM contribution guidelines](https://github.com/ESCOMP/CTSM/blob/master/CONTRIBUTING.md).
+<!-- Delete all list items below if this PR is purely Tech Note and/or User's Guide updates -->
+- [ ] The code in this PR branch builds with no errors.
+- [ ] The code in this PR branch runs with no errors. **Briefly describe tested configuration(s):**
+- [ ] This either (a) does not change answers, (b) it only changes answers at roundoff level, or (c) I have performed a scientific evaluation of the answer changes. **Which?:**
+<!-- If (c) above, include your analyses in the "Description of changes" section. -->
+- [ ] I have reviewed relevant parts of the CLM documentation [Tech Note](https://escomp.github.io/CTSM/tech_note/index.html) or [User's Guide](https://escomp.github.io/CTSM/users_guide/index.html) to determine if anything needs to be changed or added. **If it does, describe:**
+- [ ] This PR either (a) does not create a need to update the documentation or (b) includes required documentation updates (see [guidelines for contributing documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines)). **Which?:**

.github/workflows/docs-build-and-deploy.yml

@@ -11,8 +11,8 @@ on:
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   # Allows you to run this workflow manually from the Actions tab

.github/workflows/docs-pr-failure-post-comment.yml

@@ -0,0 +1,66 @@
+name: Post PR comment with doc-build failure log
+
+env:
+  DOCS_FAILURE_ARTIFACT: test-build-docs-container_failed
+
+on:
+  workflow_run:
+    workflows: ["Test building docs when they're updated"]
+    types: [completed]
+
+jobs:
+  comment:
+    if: >-
+      github.event.workflow_run.event == 'pull_request'
+      && github.event.workflow_run.conclusion == 'failure'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      actions: read
+    steps:
+      - name: Check for failure artifact
+        id: check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          gh api repos/$REPO/actions/runs/${{ github.event.workflow_run.id }}/artifacts \
+            --jq '.artifacts[] | select(.name == "${{ env.DOCS_FAILURE_ARTIFACT }}") | .id' > artifact_id.txt
+
+          if [ -s artifact_id.txt ]; then
+            echo "found=true" >> $GITHUB_OUTPUT
+          else
+            echo "found=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Download logs
+        if: steps.check.outputs.found == 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ env.DOCS_FAILURE_ARTIFACT }}
+          path: ${{ env.DOCS_FAILURE_ARTIFACT }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Post comment
+        if: steps.check.outputs.found == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          PR_NUMBER=$(cat "${DOCS_FAILURE_ARTIFACT}/pr_number.txt")
+
+          {
+            echo "### ❌ Docs build failed"
+            echo
+            echo '<details open="true">'
+            echo "<summary>Build logs</summary>"
+            echo
+            echo '```'
+            cat "${DOCS_FAILURE_ARTIFACT}/build.log"
+            echo '```'
+            echo
+            echo "</details>"
+          } > comment-body.md
+
+          gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file comment-body.md

.github/workflows/docs.yml

@@ -13,8 +13,8 @@ on:
       - '!doc/UpdateChangelog.pl'
       - '.github/workflows/docs-common.yml'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   pull_request:
@@ -27,8 +27,8 @@ on:
       - '!doc/UpdateChangelog.pl'
       - '.github/workflows/docs-common.yml'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   workflow_dispatch:
@@ -61,4 +61,159 @@ jobs:
       - name: Build docs using Docker (Podman has trouble on GitHub runners)
         id: build-docs
         run: |
-          cd doc && ./build_docs -b ${PWD}/_build -c -d
+          set -o pipefail
+          mkdir -p build-logs
+          cd doc && PYTHONUNBUFFERED=1 ./build_docs -b ${PWD}/_build -c -d 2>&1 | tee >(sed -E $'s/\x1b\\[[0-9;]*[a-zA-Z]//g' > "${GITHUB_WORKSPACE}/build-logs/build.log")
+        # The tee writes build.log for the PR comment (posted by docs-pr-failure-post-comment.yml); the inner sed strips ANSI color codes that would otherwise render as garbage in the comment.
+        # PYTHONUNBUFFERED=1 because otherwise the teed log will be out of order
+
+      # The rest of the steps only trigger on failure of above build-docs step.
+      # They upload logs that will be used by the docs-pr-failure-post-comment.yml workflow.
+
+      - name: Record PR number on failure
+        if: failure() && steps.build-docs.outcome == 'failure' && github.event_name == 'pull_request'
+        run: |
+          mkdir -p build-logs
+          echo "${{ github.event.pull_request.number }}" > build-logs/pr_number.txt
+
+      - name: Upload logs on failure
+        if: failure() && steps.build-docs.outcome == 'failure'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: test-build-docs-container_failed
+          path: build-logs/
+
+  check-docs-style:
+    if: ${{ always() }}
+    name: Check documentation against style guide
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Disallow fake degree signs
+        if: always()
+        # Prevents anyone from using the masculine ordinal indicator, as well as superscript-o/O if
+        # preceded by a digit in
+        # - Markdown math style,
+        # - reStructuredText math style,
+        # - MyST text style, and
+        # - reStructuredText text style,
+        # with or without curly brackets and/or spaces.
+        #
+        # What follows is an explanation of the regex. Keep in mind that the superscript-o will
+        # match whether it's an uppercase O or lowercase o because of the -i flag to grep, so that's
+        # not handled in the regex.
+        #
+        # Markdown math style:
+        #   Markdown math superscripts look like $^o$. There can also be curly brackets, like
+        #   $^{o}$, which would allow you to put multiple characters (including spaces) in the
+        #   superscript. The preceding digit can be inside or outside the dollar signs, again with
+        #   or without spaces.
+        #
+        #   There are two regex patterns separated by |, to handle the cases where the preceding
+        #   digit is outside or inside the dollar signs, respectively:
+        #       [0-9]\s*\\$\s*\^\{?\s*o
+        #           [0-9]   Any digit
+        #           \s*     Any number of spaces, including none
+        #           \\$     A literal dollar sign
+        #           \s*     Any number of spaces, including none
+        #           \^      A literal caret
+        #           \{?     Optionally a literal left curly bracket
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #       \\\$[0-9]+\s*\^\{?\s*o\s*\}?
+        #           \\\$    A literal dollar sign
+        #           [0-9]+  One or more digits
+        #           \s*     Any number of spaces, including none
+        #           \^      A literal caret
+        #           \{?     Optionally a literal left curly bracket
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #           \s*     Any number of spaces, including none
+        #           \}?     Optionally a literal right curly bracket
+        #
+        # MyST text style:
+        #   MyST text superscripts look like {sup}`o`. Here's the regex:
+        #       [0-9]\s*\{sup}\`\s*o\`
+        #           [0-9]   Any digit
+        #           \s*     Any number of spaces, including none
+        #           \{      A literal left curly bracket
+        #           sup     The text "sup" designating the superscript role
+        #           \}      A literal right curly bracket
+        #           \`      A literal backtick
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #           \`      A literal backtick
+        #
+        # reStructuredText text style
+        #   Similar to MyST text superscripts, but with colons instead of curly brackets: :sup:`o`.
+        #   Another difference is that spaces aren't allowed inside the backticks. Also, there has
+        #   to be a space preceding the first colon; this can be preceded by a backslash to avoid
+        #   putting an extraneous space in the rendered text. Here's the regex:
+        #       [0-9]\\\? :sup:\`o\`
+        #           [0-9]   Any digit
+        #           \\\?    Optionally a literal backslash
+        #             (A literal space)
+        #           :sup:   The text ":sup:" designating the superscript role
+        #           \`      A literal backtick
+        #           o       Lowercase o
+        #           \`      A literal backtick
+        #
+        # reStructuredText math style
+        #    Mostly the same as reStructuredText text superscripts, but with :math: instead of
+        #    :sup:. In addition, the superscript can optionally be in curly brackets. There can be
+        #    a space after the first backtick but not before the last one.
+        #
+        #   There are two regex patterns separated by |, to handle the cases where the preceding
+        #   digit is outside or inside the dollar signs, respectively:
+        #       [0-9]\\\? :math:\`\s*\^\{?\s*o\s*\}?\`
+        #           [0-9]   Any digit
+        #           \\\?    Optionally a literal backslash
+        #             (A literal space)
+        #           :math:  The text ":math:" designating the math role
+        #           \`      A literal backtick
+        #           \s*     Any number of spaces, including none
+        #           \^      A literal caret
+        #           \{?     Optionally a literal left curly bracket
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #           \s*     Any number of spaces, including none
+        #           \}?     Optionally a literal right curly bracket
+        #           \`      A literal backtick
+        #       :math:\`\s*[0-9]+\s*\^\{?\s*o\s*\}?\`
+        #           :math:  The text ":math:" designating the math role
+        #           \`      A literal backtick
+        #           \s*     Any number of spaces, including none
+        #           [0-9]+  One or more digits
+        #           \s*     Any number of spaces, including none
+        #           \^      A literal caret
+        #           \{?     Optionally a literal left curly bracket
+        #           \s*     Any number of spaces, including none
+        #           o       Lowercase o
+        #           \s*     Any number of spaces, including none
+        #           \}?     Optionally a literal right curly bracket
+        #           \`      A literal backtick
+        run: |
+          set +e
+          instances_of_fake_degree_signs="$(grep -ionE "[0-9]\s*\\$\s*\^\{?\s*o|\\\$[0-9]+\s*\^\{?\s*o\s*\}?|[0-9]\s*\{sup}\`\s*o\`|[0-9]\\\? :sup:\`o\`|[0-9]\\\? :math:\`\s*\^\{?\s*o\s*\}?\`| :math:\`\s*[0-9]+\s*\^\{?\s*o\s*\}?\`|º" $(find doc -name "*.md" -or -name "*.rst"))"
+          set -e
+          if [[ "$instances_of_fake_degree_signs" ]] then
+            echo -e "Instances of superscript-o or masculine ordinal indicator (º) instead of degree sign (°):\n${instances_of_fake_degree_signs}"
+            echo -e "\nSee https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-style-guide.html"
+            exit 1
+          fi
+          exit 0
+
+      - name: Disallow curly apostrophes/quotes
+        if: always()
+        run: |
+          set +e
+          instances_of_curlies="$(grep -onE "“|”|‘|’" $(find doc -name "*.md" -or -name "*.rst"))"
+          set -e
+          if [[ "$instances_of_curlies" ]] then
+            echo -e "Instances of curly apostrophes and/or quote marks:\n${instances_of_curlies}"
+            exit 1
+          fi
+          exit 0

.gitmodules

@@ -28,7 +28,7 @@
 [submodule "fates"]
 path = src/fates
 url = https://github.com/NGEET/fates
-fxtag = sci.1.91.1_api.43.1.0
+fxtag = sci.1.92.5_api.46.0.0
 fxrequired = AlwaysRequired
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/NGEET/fates
@@ -68,39 +68,39 @@ fxDONOTUSEurl = https://github.com/ESCOMP/mizuRoute
 [submodule "ccs_config"]
 path = ccs_config
 url = https://github.com/ESMCI/ccs_config_cesm.git
-fxtag = ccs_config_cesm1.0.79
+fxtag = ccs_config_cesm1.0.83
 fxrequired = ToplevelRequired
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESMCI/ccs_config_cesm.git
 
 [submodule "cime"]
 path = cime
 url = https://github.com/ESMCI/cime
-fxtag = cime6.1.169
+fxtag = cime6.2.2
 fxrequired = ToplevelRequired
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESMCI/cime
 
 [submodule "cmeps"]
 path = components/cmeps
 url = https://github.com/ESCOMP/CMEPS.git
-fxtag = cmeps1.1.37
+fxtag = cmeps1.1.47
 fxrequired = ToplevelRequired
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESCOMP/CMEPS.git
 
 [submodule "cdeps"]
 path = components/cdeps
 url = https://github.com/ESCOMP/CDEPS.git
-fxtag = cdeps1.0.93
+fxtag = cdeps1.0.96
 fxrequired = ToplevelRequired
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESCOMP/CDEPS.git
 
 [submodule "share"]
 path = share
 url = https://github.com/ESCOMP/CESM_share
-fxtag = share1.1.19
+fxtag = share1.1.20
 fxrequired = ToplevelRequired
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESCOMP/CESM_share
@@ -124,7 +124,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/mpi-serial
 [submodule "doc-builder"]
 path = doc/doc-builder
 url = https://github.com/ESMCI/doc-builder
-fxtag = v2.2.6
+fxtag = v3.2.1
 fxrequired = ToplevelOptional
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESMCI/doc-builder