New procedure for updating .md and .yaml files (#122)

Because it is a bit of a hassle for PR authors to have to make changes to multiple files, #117 attempted to automate the process using the `tools/write_standard_name_table.py` tool. However, this new GitHub action could not run automatically due to branch protection rules on the `main` branch. Rather than remove those restrictions, this PR reverts to the old method of manual updates, but provides more extensive documentation and user prompts to do this updating properly.

Author: mkavulich

.github/PULL_REQUEST_TEMPLATE

@@ -1,5 +1,22 @@
 <!-- Please read all instructions, then fill out the following template.-->
 
+<!-- If this PR includes changes to standard names, you must update the Markdown and YAML files
+to be consistent with your changes to standard_names.xml.
+
+This can be done by running the following commands:
+
+    tools/write_standard_name_table.py --output-format md standard_names.xml
+
+This script requires the pyyaml Python package; to install with pip use command:
+    python -m pip install PyYaml
+ For conda users, environment file tools/environment.yml is provided.
+
+Note that the above procedure assumes your changes were made to standard_names.xml If you instead
+made your changes to one of the human-readable files (Metadata-standard-names.md or
+Metadata-standard-names.yaml), YOU MUST UPDATE THE FILE standard_names.xml MANUALLY, otherwise your
+changes may be lost.
+-->
+
 <!-- Include a short, descriptive title in the field above. If this PR is for a branch other than
 `main`, include the destination branch name in brackets at the beginning, e.g.:
 
@@ -15,6 +32,12 @@ Developers listed in the CODEOWNERS file will automatically be assigned to revie
 If your contribution should be reviewed by anyone else, assign those reviewers manually from the
 menu at right, or by tagging them with @USERNAME in the Description text.
 
+Changes to standard names and/or descriptions should be made in the standard_names.xml file. The
+files Metadata-standard-names.md and Metadata-standard-names.yaml will need to be updated before
+a pull request is merged; this can be done manually by the PR author using the script
+tools/write_standard_name_table.py or will be done by the Code Manager prior to merging via Github
+Actions.
+
 Be sure to check in on the PR regularly to respond to comments/questions/reviews!
 --> 
 

.github/workflows/commit_to_main.yml

@@ -72,14 +72,31 @@ jobs:
 
       - name: Test rendering xml file to markdown
         run: |
+          # Checks if the saved markdown matches freshly rendered markdown.
+          # If this fails, prompt user to update
           tools/write_standard_name_table.py --output-format md standard_names.xml
-          echo "The following changes will be committed when this pull request is merged (git diff Metadata-standard-names.md; "
-          echo "assuming that 'Metadata-standard-names.md' wasn't updated and matches the version in the authoritative branch):"
-          git diff Metadata-standard-names.md
+          if ! git diff --exit-code --quiet; then
+            echo "❌ Detected that Metadata-standard-names.md is not consistent with standard_names.xml"
+            echo "✅ To fix: Run the following command locally and commit the result:"
+            echo "    tools/write_standard_name_table.py --output-format md standard_names.xml"
+            echo "📘 This script requires the pyyaml Python package; to install with pip use command:"
+            echo "    python -m pip install PyYaml"
+            echo "📘 For conda users, environment file tools/environment.yml is provided."
+            echo
+            exit 1
+          fi
 
       - name: Test rendering xml file to yaml
         run: |
           tools/write_standard_name_table.py --output-format yaml standard_names.xml
-          echo "The following changes will be committed when this pull request is merged (git diff Metadata-standard-names.yaml; "
-          echo "assuming that 'Metadata-standard-names.yaml' wasn't updated and matches the version in the authoritative branch):"
-          git diff Metadata-standard-names.yaml
+          if ! git diff --exit-code --quiet; then
+            echo "❌ Detected that Metadata-standard-names.yaml is not consistent with standard_names.xml"
+            echo "✅ To fix: Run the following command locally and commit the result:"
+            echo "    tools/write_standard_name_table.py --output-format yaml standard_names.xml"
+            echo "📘 This script requires the pyyaml Python package; to install with pip use command:"
+            echo "    python -m pip install PyYaml"
+            echo "📘 For conda users, environment file tools/environment.yml is provided."
+            echo
+            exit 1
+          fi
+

.github/workflows/pull_request_ci.yml

@@ -1,4 +1,4 @@
-# Earth System Modeling Standard Name Library - add some chunk here to test auto update
+# Earth System Modeling Standard Name Library
 #### Table of Contents
 * [dimensions](#dimensions)
 * [constants](#constants)

Metadata-standard-names.md

@@ -1,4 +1,4 @@
-library_name: Earth System Modeling Standard Name Library - add some chunk here to test auto update
+library_name: Earth System Modeling Standard Name Library
 sections:
 - name: dimensions
   comment: 'Dimension standard names may come in sets of six related standard names

Metadata-standard-names.yaml

@@ -4,6 +4,6 @@ The Earth System Modeling Standard Names Repository contains community-accepted
 
 Rules governing the designation and format of standard names can be found in [StandardNamesRules.rst](https://github.com/ESCOMP/ESMStandardNames/blob/main/StandardNamesRules.rst) 
 
-A [Markdown file describing the standard names is included](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.md), as well as a [Yaml version of the XML file](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.yaml).
+A [Markdown file describing the standard names is included](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.md), as well as a [YAML version of the XML file](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.yaml).
 
-Edits to standard names must be made in the xml file `standard_names.xml` only. When pull requests are merged into the authoritative branch, a tool is run in GitHub actions that automatically updates the human-readable standard name Markdown file and the Yaml version.
+Edits to standard names must be made in the xml file `standard_names.xml` only. When a pull request is opened into the main branch, the YAML and Markdown files should be updated using the `tools/write_standard_name_table.py` script. This can be done manually by the pull request author, or by activating the GitHub action available on an open pull request.

README.md

@@ -0,0 +1,5 @@
+name: test
+channels:
+  - conda-forge
+dependencies:
+  - pyyaml