Merge updates from https://github.com/nfdi4cat/voc4cat-template

.github/workflows/ci-pr.yml

@@ -1,11 +1,5 @@
 # This action runs when a pull request to main is created or updated
-# (but not when it is merged).
-#
-# Workflow steps:
-# - run voc4cat to update xlsx file and create turtle file
-# - store artifacts (even on failure)
-# - remove xlsx-vocab file from PR
-# - commit on behalf of the PR-author using "voc4cat-CI-bot" as committer
+# (but not when it is merged into main).
 
 name: CI on pull request create or update
 on:
@@ -34,7 +28,8 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v3
+      - name: Checkout PR branch into cwd
+        uses: actions/checkout@v3
         with:
           # Checkout the fork/head-repository to push changes to the fork.
           # Without this the base repository will be checked out and committed to.
@@ -43,6 +38,16 @@ jobs:
           # Checkout the branch made in the fork.
           ref: ${{ github.head_ref }}
 
+      - name: Checkout main branch into directory _main_branch/
+        uses: actions/checkout@v3
+        with:
+          ref: main
+          path: _main_branch
+          # This sparse-checkout includes all toplevel files and everything below vocabularies/
+          sparse-checkout: |
+            vocabularies/
+          fetch-depth: 1
+
       - uses: actions/setup-python@v4
         with:
           python-version: '3.11'
@@ -51,33 +56,31 @@ jobs:
         run: |
           python -VV
           python -m pip install --upgrade pip setuptools wheel
+
           python -m pip install git+https://github.com/nfdi4cat/voc4cat-tool.git@main
-        # from private repo: python -m pip install git+https://anon:${{ SECRETS.READ_PAT_VOC4CAT }}@github.com/dalito/voc4cat-tool.git@main
+          # from private repo: python -m pip install git+https://anon:${{ SECRETS.READ_PAT_VOC4CAT }}@github.com/dalito/voc4cat-tool.git@main
+
+      - name: Dynamically set RUN_DATE environment variable
+        run: echo "RUN_DATE=$(date +'%Y-%m-%dT%H%M')" >> $GITHUB_ENV
 
       - name: Run voc4cat
         run: |
           voc4cat --version
-          ls -l outbox/ || echo "outbox directory does not exist."
-          voc4cat --check --forward --docs pylode --output-directory outbox inbox-excel-vocabs/ |& tee voc4cat.log
-          VOC4CAT_EXIT_CODE=${PIPESTATUS[0]}
-          mv voc4cat.log outbox
-          ls -l outbox/ || echo "outbox directory does not exist."
-          echo voc4cat exit code: ${VOC4CAT_EXIT_CODE}
-          exit ${VOC4CAT_EXIT_CODE}
+          voc4cat -v --ci-check --config _main_branch/idranges.toml --check --forward --logfile voc4cat.log --docs pylode --output-directory outbox inbox-excel-vocabs/
+
+      - name: Merge changes into vocabulary (in PR branch)
+        run: |
+          merge_vocab --logfile voc4cat.log outbox/ vocabularies/
+          git status
 
       - name: Store artifacts
         if: ${{ always() }}
         uses: actions/upload-artifact@v3
         with:
-          name: voc4cat-outbox-run${{ GITHUB.RUN_ID }}
+          name: voc4cat-outbox_${{ env.RUN_DATE }}_run${{ GITHUB.RUN_ID }}
           path: outbox/
 
-      - name: Merge changes into vocabulary
-        run: |
-          merge_vocab outbox/ vocabularies/
-          git status
-
-      - name: Add vocabulary changes
+      - name: Add/stage vocabulary changes
         # Pin third party action (v4.16.0)
         uses: stefanzweifel/git-auto-commit-action@3ea6ae190baf489ba007f7c92608f33ce20ef04a
         with:
@@ -89,12 +92,9 @@ jobs:
           git rm inbox-excel-vocabs/\*.xlsx || echo "No xlsx files to remove."
           git status
 
-      - name: Commit vocabulary changes & xlsx removal
+      - name: Commit vocabulary changes & xlsx cleanup on behalf of PR-author
         # Pin third party action (v4.16.0)
         uses: stefanzweifel/git-auto-commit-action@3ea6ae190baf489ba007f7c92608f33ce20ef04a
         with:
           commit_user_name: voc4cat-CI-bot
           commit_message: 'CI: vocabulary update in ${{ GITHUB.SERVER_URL }}/${{ GITHUB.REPOSITORY }}/actions/runs/${{ GITHUB.RUN_ID }}'
-
-# Lit:
-# https://github.com/stefanzweifel/git-auto-commit-action

.gitignore

@@ -104,3 +104,6 @@ _version.py
 # output dir
 outbox/
 publish/
+
+# Special dir for a clone of main branch in gh-actions
+_main_branch

README.md

@@ -10,49 +10,44 @@ It uses the [voc4cat-tool](https://github.com/nfdi4cat/voc4cat-tool) and GitHub
 
 ## Basic principles
 
-All vocabularies managed here have the same standard contribution process,
+The process to contribute to the **voc4cat vocabulary** is as follows:
 
-- get and update the vocablary file (xlsx),
+- get and update the vocabulary file (xlsx),
 - submit a pull request with the updated file,
 - collaborate on the pull request with editors or other github users,
-- approval and merge of the pull request.
 
-Finally the SKOS-vocabularies land in the folder `vocabularies` in turtle-format.
+After approval your pull request will be merged by the editors. Immediately afterwards your contribution will be included in the SKOS-vocabulary file in the `vocabularies`-folder and it will also be reflected in the documentation that is automatically updated.
 
-In addition, HTML-documentation is created automatically and published on github-pages.
-
-- The general url is `https://{gh-org-name}.github.io/{repository-name}/{vocabulary-name}/`
-- In repository `nfdi4cat/voc4cat` the vocabulary `voc4cat` is documented at [https://nfdi4cat.github.io/voc4cat/voc4cat/](https://nfdi4cat.github.io/voc4cat/voc4cat/)
+- The vocabulary `voc4cat` is documented at [https://nfdi4cat.github.io/voc4cat/voc4cat/](https://nfdi4cat.github.io/voc4cat/voc4cat/)
 
 ## Contributing to vocabularies
 
-To discuss about the SKOS-vocabularies maintained here, create an [issue](https://github.com/nfdi4cat/voc4cat/issues).
+To discuss about the **voc4cat**-vocabulary maintained here, create an [issue](https://github.com/nfdi4cat/voc4cat/issues).
 
-To contribute new concepts or collections or change existing ones, you may either submit your contributions as Excel-file or (as an expert) as new/changed turtle file.
+To contribute new concepts or collections or change existing ones, you may either submit your contributions as Excel/xlsx-file or (as an expert) as new/changed turtle file.
 
 > *To try out the workflow with some example data, you may use  [voc4cat-playground](https://github.com/nfdi4cat/voc4cat-playground) which is identical to this repository but will be purged from time to time.*
 
 Here are the steps for submitting updates in Excel.
 
-- Get the Excel-vocabulary file
-  - For an existing vocabulary, the latest version of the vocabulary is always available via github-pages.
-    - The general url is `https://{gh-org-name}.github.io/{repository-name}/{vocabulary-name}.xlsx`
-    - For example in nfdi4cat/voc4cat the vocabulary `voc4cat` can be downloaded from [https://nfdi4cat.github.io/voc4cat/voc4cat.xlsx](https://nfdi4cat.github.io/voc4cat/voc4cat.xlsx)
+- Get the Excel/xlsx-vocabulary file
+  - The latest version of the vocabulary is always available via github-pages.
+    - The xlsx-file for `voc4cat` can be downloaded from [https://nfdi4cat.github.io/voc4cat/voc4cat.xlsx](https://nfdi4cat.github.io/voc4cat/voc4cat.xlsx)
 - Make changes to the Excel file
-- Add the Excel file to your clone of the repository into the folder `inbox-excel-vocabs`
-  - The name of the Excel-file must match the vocabulary that you want to update (e.g. myvoc.xlsx to update a vocabulary named "myvoc").
-  - Important: In this repository we accept only files named `voc4cat.xlsx`.
-- Create a pull request with the updated Excel-file on github.
+- Add the xlsx file to your clone of the repository into the folder `inbox-excel-vocabs`
+  - The name of the file must match the vocabulary that you want to update. So do not change the filename, but keep `voc4cat.xlsx`.
+- Create a pull request with the updated Excel-file in this repository.
   - Please describe your changes and the motivation for the changes in the pull request note or link to an issue with this information. This will help reviewers to understand the proposed change and decide about it.
 - Your pull request will be processed automatically by a CI/CD pipeline that typically runs less than a minute.
 - Review the artifacts/logs generated by the CI pipeline.
+  - The [workflow artifact](https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts) will contain an updated xlsx file that is recreated from the updated turtle-file.
 - If all is good your contribution will be either
   - directly merged by the maintainers
   - or a discussion will be started about what else is needed
   - or why the proposed change may not fit.
-- If you need to fix something just update the pull request branch. This will trigger the pipeline to run again.
+- If you need to fix something update the pull request branch. This will trigger the pipeline to run again.
 
-Finally, when the proposed merge request is accepted, your changes will be integrated in the vocabularies in the folder [vocabularies](https://github.com/nfdi4cat/voc4cat/tree/main/vocabularies).
+Finally, when the proposed merge request is accepted, your changes will be integrated in the vocabulary in the folder [vocabularies](https://github.com/nfdi4cat/voc4cat/tree/main/vocabularies).
 
 See [inbox-excel-vocabs/README.md](inbox-excel-vocabs/README.md) for a minimal example how to test the submission process.
 
@@ -76,6 +71,7 @@ To discuss about the tool that converts Excel to SKOS in gh-actions of this temp
 
 ### Vocabularies
 
+
 All vocabularies in this repository are CC0 licensed, see [LICENSE](LICENSE) for details.
 
 ### Voc4cat template

idranges.toml

@@ -1,41 +1,48 @@
-# Documentation of the TOML format: https://toml.io/en/latest
 
 # ==== General Configuration ====
+# Documentation of the TOML format: https://toml.io/en/latest
 
 # Allow only a single vocabulary (default) or multiple vocabularies in the repository.
 single_vocab = true
 
 # ==== Configuration for vocabulary "voc4cat" ====
 
-[[voc4cat]]
+# The name of the vocabulary is used as section name.
+# It should match the filename-stem of the vocabulary files.
+[vocabs.voc4cat]
 # Length of integer IDs in vocabulary. IDs will be left-padded with zeros to specified length.
 id_length = 7
+# permanent part of IRIs defined in the vocabulary
+permanent_iri_part = "https://w3id.org/nfdi4cat/voc4cat_"
 
 # Section to configure checks (useful in CI pipeline)
-[[voc4cat.checks]]
-no_delete = true
+[vocabs.voc4cat.checks]
+# Deleting allowed (relevant in CI-pipeline)
+allow_delete = false
 
+[vocabs.voc4cat.prefix_map]
+v4c = "https://w3id.org/nfdi4cat/voc4cat_"
 # Section of IDranges for coordinating the allocation of numeric ID ranges to
 # contributors for each vocabulary. Each idrange contains the same keys:
 #
-#   first_id = <int>              - first reserved integer ID in idrange
-#   last_id = <int>               - last reserved integer ID in idrange
-#   gh_username = "<string>"      - username on github
-#   orcid = "<string>"            - contributor's ORCID, e.g. "0000-0001-2345-6789"
-#   organisation_ror_id = "<url>" - ROR of home organisation, e.g. "https://ror.org/04fa4r544"
+# first_id = <int>            - first reserved integer ID in idrange
+# last_id = <int>             - last reserved integer ID in idrange
+# gh_name = "<string>"        - user or organisation name on github
+# orcid = "<string> or <url>" - contributor's ORCID, e.g. "0000-0002-1825-0097" or "https://orcid.org/0000-0002-1825-0097"
+# ror_id = "<url>"            - ROR identifier of home organisation, e.g. "https://ror.org/04fa4r544"
 
-[[voc4cat.idrange]]
+[[vocabs.voc4cat.id_range]]
 first_id = 1
 last_id = 5000
-gh_username = "nmoust"
+gh_name = "nmoust"
 orcid = "0000-0002-6242-2167"
-organisation_ror_id = "https://ror.org/029hg0311"
+ror_id = "https://ror.org/029hg0311"
 
-[[voc4cat.idrange]]
+[[vocabs.voc4cat.id_range]]
 first_id = 5001
 last_id = 6000
-gh_username = "dalito"
+gh_name = "dalito"
 orcid = "0000-0002-5898-1820"
-organisation_ror_id = "https://ror.org/029hg0311"
+ror_id = "https://ror.org/029hg0311"
 
-# Continue with as many [[idrange]] sections as needed.
+# Continue with as many [[vocabs.voc4cat.id_range]] sections as needed.

inbox-excel-vocabs/README.md

@@ -4,5 +4,8 @@ See also [../README.md](../README.md) for the steps in the contribution process.
 
 - Copy the file with your updates to this folder
 - Rename it to `voc4cat.xlsx`.
-- Add the file to git and submit a pull request
-- The vocabulary `vocabularies/voc4cat.ttl` is generated (or updated) via gh-action and committed to your pull request. The Excel file is removed from the pull request. However, the Excel file along with a log-file and the generated documentation can be [downloaded as workflow artifact](https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts).
+- Add the file to git and submit a pull request.
+- If there is no validation error the vocabulary `vocabularies/voc4cat.ttl` is updated via gh-actions and committed to your pull request. The Excel file is removed from the pull request.
+- If there are errors, you can examine them in the run log.
+- In any case (error or not) you can download the xlsx file along with a log-file and the generated documentation as [workflow artifact](https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts).
+The xlsx-file in the artifact will be the updated one that is recreated from the updated turtle-file.