From 4027210eb8548d5a902a3bc8d2f3fa48b908ba9a Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 17 Jul 2025 10:04:28 -0600 Subject: [PATCH 01/10] Switch updating of metadata files to workflow dispatch; this way it can be run manually as the user desires before merge --- .github/workflows/commit_to_main.yml | 2 +- .github/workflows/pull_request_ci.yml | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/commit_to_main.yml b/.github/workflows/commit_to_main.yml index 42ab65f..6c69396 100644 --- a/.github/workflows/commit_to_main.yml +++ b/.github/workflows/commit_to_main.yml @@ -1,7 +1,7 @@ name: Render xml standard name dictionary to markdown and yaml and commit to repository on: - push: + workflow_dispatch: branches: - main diff --git a/.github/workflows/pull_request_ci.yml b/.github/workflows/pull_request_ci.yml index df746e0..c7a7ebb 100644 --- a/.github/workflows/pull_request_ci.yml +++ b/.github/workflows/pull_request_ci.yml @@ -72,14 +72,14 @@ 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 + checksum=$(sha256sum Metadata-standard-names.md) 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 + test "$checksum" = "$(sha256sum Metadata-standard-names.md)" || exit "Markdown file Metadata-standard-names.md must be updated; see documentation for details" - name: Test rendering xml file to yaml run: | + checksum=$(sha256sum Metadata-standard-names.yaml) 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 + test "$checksum" = "$(sha256sum Metadata-standard-names.yaml)" || exit "YAML file Metadata-standard-names.yaml must be updated; see documentation for details" From 13c93a12653ae3d04409d860698375a76e25993f Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 17 Jul 2025 10:15:58 -0600 Subject: [PATCH 02/10] New proposed instructions: updates to .md and .yaml can be done by author or code manager --- .github/PULL_REQUEST_TEMPLATE | 6 ++++++ README.md | 4 ++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE index 72e61c9..b20ec93 100644 --- a/.github/PULL_REQUEST_TEMPLATE +++ b/.github/PULL_REQUEST_TEMPLATE @@ -15,6 +15,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! --> diff --git a/README.md b/README.md index 138c7c9..dfbd491 100644 --- a/README.md +++ b/README.md @@ -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. From 05e2c2df8d60a522078e296ed783bd6462d50e8a Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 17 Jul 2025 10:23:46 -0600 Subject: [PATCH 03/10] Rename test file, dont restrict to main branch --- .../workflows/{commit_to_main.yml => update_md_and_yaml.yml} | 2 -- 1 file changed, 2 deletions(-) rename .github/workflows/{commit_to_main.yml => update_md_and_yaml.yml} (98%) diff --git a/.github/workflows/commit_to_main.yml b/.github/workflows/update_md_and_yaml.yml similarity index 98% rename from .github/workflows/commit_to_main.yml rename to .github/workflows/update_md_and_yaml.yml index 6c69396..fced4ad 100644 --- a/.github/workflows/commit_to_main.yml +++ b/.github/workflows/update_md_and_yaml.yml @@ -2,8 +2,6 @@ name: Render xml standard name dictionary to markdown and yaml and commit to rep on: workflow_dispatch: - branches: - - main jobs: update-md-and-yaml: From f4a333ca4ac28499fb1b3d96cea060a1158ac810 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 17 Jul 2025 10:30:28 -0600 Subject: [PATCH 04/10] Manually update human-readable tables --- Metadata-standard-names.md | 2 +- Metadata-standard-names.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md index 35c7921..a8b9f45 100644 --- a/Metadata-standard-names.md +++ b/Metadata-standard-names.md @@ -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) diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml index 88fd9db..d7f8f85 100644 --- a/Metadata-standard-names.yaml +++ b/Metadata-standard-names.yaml @@ -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 From dfa7f887abda362b4cc9a94700c3be75768d30e1 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 23 Jul 2025 15:19:30 -0600 Subject: [PATCH 05/10] Revert "Manually update human-readable tables", test using git diff rather than checksum --- .github/workflows/pull_request_ci.yml | 3 +-- Metadata-standard-names.md | 2 +- Metadata-standard-names.yaml | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/pull_request_ci.yml b/.github/workflows/pull_request_ci.yml index c7a7ebb..11a5867 100644 --- a/.github/workflows/pull_request_ci.yml +++ b/.github/workflows/pull_request_ci.yml @@ -74,9 +74,8 @@ jobs: run: | # Checks if the saved markdown matches freshly rendered markdown. # If this fails, prompt user to update - checksum=$(sha256sum Metadata-standard-names.md) tools/write_standard_name_table.py --output-format md standard_names.xml - test "$checksum" = "$(sha256sum Metadata-standard-names.md)" || exit "Markdown file Metadata-standard-names.md must be updated; see documentation for details" + git diff --exit-code || exit "Markdown file Metadata-standard-names.md must be updated; see documentation for details" - name: Test rendering xml file to yaml run: | diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md index a8b9f45..35c7921 100644 --- a/Metadata-standard-names.md +++ b/Metadata-standard-names.md @@ -1,4 +1,4 @@ -# Earth System Modeling Standard Name Library +# Earth System Modeling Standard Name Library - add some chunk here to test auto update #### Table of Contents * [dimensions](#dimensions) * [constants](#constants) diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml index d7f8f85..88fd9db 100644 --- a/Metadata-standard-names.yaml +++ b/Metadata-standard-names.yaml @@ -1,4 +1,4 @@ -library_name: Earth System Modeling Standard Name Library +library_name: Earth System Modeling Standard Name Library - add some chunk here to test auto update sections: - name: dimensions comment: 'Dimension standard names may come in sets of six related standard names From aafbf995fb0405d950b575ecd1fa0e4a71e1ac0c Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 27 Aug 2025 16:43:30 -0600 Subject: [PATCH 06/10] Adding more verbose message for when markdown/yaml files have not been updated --- .github/workflows/pull_request_ci.yml | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pull_request_ci.yml b/.github/workflows/pull_request_ci.yml index 11a5867..2bba3c0 100644 --- a/.github/workflows/pull_request_ci.yml +++ b/.github/workflows/pull_request_ci.yml @@ -75,10 +75,24 @@ jobs: # 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 - git diff --exit-code || exit "Markdown file Metadata-standard-names.md must be updated; see documentation for details" + 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 "📘 See documentation for more details." + echo + exit 1 + fi - name: Test rendering xml file to yaml run: | - checksum=$(sha256sum Metadata-standard-names.yaml) tools/write_standard_name_table.py --output-format yaml standard_names.xml - test "$checksum" = "$(sha256sum Metadata-standard-names.yaml)" || exit "YAML file Metadata-standard-names.yaml must be updated; see documentation for details" + 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 md standard_names.xml" + echo "📘 See documentation for more details." + echo + exit 1 + fi + From f42b1dc952c35d996c98aad43b286d6f5929f7c5 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 27 Aug 2025 16:55:01 -0600 Subject: [PATCH 07/10] Make changes suggested by script, add note about needed python package --- .github/workflows/pull_request_ci.yml | 2 ++ Metadata-standard-names.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pull_request_ci.yml b/.github/workflows/pull_request_ci.yml index 2bba3c0..f25aacd 100644 --- a/.github/workflows/pull_request_ci.yml +++ b/.github/workflows/pull_request_ci.yml @@ -79,6 +79,7 @@ jobs: 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 "📘 Note that this script requires the pyyaml Python package." echo "📘 See documentation for more details." echo exit 1 @@ -91,6 +92,7 @@ jobs: 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 md standard_names.xml" + echo "📘 Note that this script requires the pyyaml Python package." echo "📘 See documentation for more details." echo exit 1 diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md index 35c7921..a8b9f45 100644 --- a/Metadata-standard-names.md +++ b/Metadata-standard-names.md @@ -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) From 4ec3614a08196c72c88af9c782960de376de9c1f Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 27 Aug 2025 16:58:52 -0600 Subject: [PATCH 08/10] Make update to yaml, fix instructive message --- .github/workflows/pull_request_ci.yml | 2 +- Metadata-standard-names.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pull_request_ci.yml b/.github/workflows/pull_request_ci.yml index f25aacd..b1fd018 100644 --- a/.github/workflows/pull_request_ci.yml +++ b/.github/workflows/pull_request_ci.yml @@ -91,7 +91,7 @@ jobs: 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 md standard_names.xml" + echo " tools/write_standard_name_table.py --output-format yaml standard_names.xml" echo "📘 Note that this script requires the pyyaml Python package." echo "📘 See documentation for more details." echo diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml index 88fd9db..d7f8f85 100644 --- a/Metadata-standard-names.yaml +++ b/Metadata-standard-names.yaml @@ -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 From 64df4e93b90fcce843859383d42fcacdd5329895 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 27 Aug 2025 17:21:14 -0600 Subject: [PATCH 09/10] Remove automated workflow, reverting back to manual updates. Also include some more help for installing needed python package --- .github/workflows/pull_request_ci.yml | 10 +++-- .github/workflows/update_md_and_yaml.yml | 54 ------------------------ tools/environment.yml | 5 +++ 3 files changed, 11 insertions(+), 58 deletions(-) delete mode 100644 .github/workflows/update_md_and_yaml.yml create mode 100644 tools/environment.yml diff --git a/.github/workflows/pull_request_ci.yml b/.github/workflows/pull_request_ci.yml index b1fd018..c6f3283 100644 --- a/.github/workflows/pull_request_ci.yml +++ b/.github/workflows/pull_request_ci.yml @@ -79,8 +79,9 @@ jobs: 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 "📘 Note that this script requires the pyyaml Python package." - echo "📘 See documentation for more details." + 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 @@ -92,8 +93,9 @@ jobs: 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 "📘 Note that this script requires the pyyaml Python package." - echo "📘 See documentation for more details." + 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 diff --git a/.github/workflows/update_md_and_yaml.yml b/.github/workflows/update_md_and_yaml.yml deleted file mode 100644 index fced4ad..0000000 --- a/.github/workflows/update_md_and_yaml.yml +++ /dev/null @@ -1,54 +0,0 @@ -name: Render xml standard name dictionary to markdown and yaml and commit to repository - -on: - workflow_dispatch: - -jobs: - update-md-and-yaml: - name: Render xml to markdown and yaml and commit - runs-on: ubuntu-latest - - permissions: - contents: write - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Setup Python - uses: actions/setup-python@v4 - with: - python-version: "3.x" - - - name: Configure git - run: | - git config --global user.name "github-actions[bot]" - git config --global user.email "github-actions[bot]@users.noreply.github.com" - - - name: Install dependencies - run: | - sudo apt-get update - sudo apt-get -y install libxml2-utils - python -m pip install --upgrade pip - python -m pip install PyYaml - - - name: Render xml to markdown - run: | - tools/write_standard_name_table.py --output-format md standard_names.xml - echo "The following changes will be committed (git diff Metadata-standard-names.md):" - git diff Metadata-standard-names.md - git add Metadata-standard-names.md - - - name: Rendering xml to yaml - run: | - tools/write_standard_name_table.py --output-format yaml standard_names.xml - echo "The following changes will be committed (git diff Metadata-standard-names.yaml):" - git diff Metadata-standard-names.yaml - git add Metadata-standard-names.yaml - - - name: Commit and push changes - run: | - git commit -m "Update Metadata-standard-names.{md,yaml} from standard_names.xml" || echo "No changes to commit" - git push - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/tools/environment.yml b/tools/environment.yml new file mode 100644 index 0000000..2090fcd --- /dev/null +++ b/tools/environment.yml @@ -0,0 +1,5 @@ +name: test +channels: + - conda-forge +dependencies: + - pyyaml From 3d99bc74ac9c74e5d20ca527c20757ecf5b91158 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 27 Aug 2025 17:36:20 -0600 Subject: [PATCH 10/10] Update PR template with instructions for updating human-readable dictionary files --- .github/PULL_REQUEST_TEMPLATE | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE index b20ec93..3f80572 100644 --- a/.github/PULL_REQUEST_TEMPLATE +++ b/.github/PULL_REQUEST_TEMPLATE @@ -1,5 +1,22 @@ + +