Finalize release workflows

Update and add documentation for how to release a new BattINFO version
as well as how to release the documentation.

.github/utils/publish_ontologies.py

@@ -46,21 +46,21 @@ class VersionIRI(str):
     """
 
     _VERSION_IRI_REGEX = re.compile(
-        r"https?://(?P<domain>[a-zA-Z._-]+)/(?P<path>[a-zA-Z_-]+(/[a-zA-Z_-]+)*)"
-        r"/(?P<version>[0-9a-zA-Z._-]+)(/(?P<name>[a-zA-Z_-]+))?(/(?P<filename>[a-zA-Z_.-]+))?"
+        r"https?://(?P<domain>[a-zA-Z._-]+)/(?P<path>[a-zA-Z_-]+(?:/[a-zA-Z_-]+)*)"
+        r"/(?P<version>[0-9a-zA-Z._-]+)(?:/(?P<name>[a-zA-Z_-]+))?(?:/(?P<filename>[a-zA-Z_.-]+))?"
     )
 
     def __init__(self, version_iri: str) -> None:
         match = self._VERSION_IRI_REGEX.fullmatch(version_iri)
         if match is None:
             raise ValueError(f"Could not parse versionIRI {version_iri!r}")
-        domain, path, version, name, filename = match.groups()
-        self._domain = domain
-        self._path = path
-        self._top_name = path.rsplit("/", 1)[-1]
-        self._version = version
-        self._name = name if name else None
-        self._filename = filename if filename else None
+        parts = match.groupdict()
+        self._domain = parts["domain"]
+        self._path = parts["path"]
+        self._top_name = parts["path"].rsplit("/", 1)[-1]
+        self._version = parts["version"]
+        self._name = parts.get("name", None)
+        self._filename = parts.get("filename", None)
 
     @property
     def domain(self) -> str:

.github/workflows/cd_update_version.yml

@@ -9,7 +9,8 @@ env:
   GIT_USER_EMAIL: "[email protected]"
 
 jobs:
-  update_version:
+  update-version:
+    name: Update version
     runs-on: ubuntu-latest
 
     steps:
@@ -27,4 +28,24 @@ jobs:
         pip install -U setuptools wheel
 
     - name: Update version
-      run: |
+      run: |
+        # Update BattINFO versions in battinfo.ttl versionIRI and versionInfo as well as the reference in catalog-v001.xml
+        sed -i "s|BattINFO/[0-9]\.[0-9]\.[0-9]/battinfo|BattINFO/${GITHUB_REF#refs/tags/v}/battinfo|g" battinfo.ttl
+        sed -i "s|versionInfo \".*\"|versionInfo \"${GITHUB_REF#refs/tags/v}\"|g" battinfo.ttl
+        sed -i "s|BattINFO/[0-9]\.[0-9]\.[0-9]/battinfo|BattINFO/${GITHUB_REF#refs/tags/v}/battinfo|g" catalog-v001.xml
+
+    - name: Commit changes
+      run: |
+        # Set up git
+        git config --local user.name "${GIT_USER_NAME}"
+        git config --local user.email "${GIT_USER_EMAIL}"
+
+        # Commit and push changes
+        git add battinfo.ttl catalog-v001.xml
+        git commit -m "Update version to ${GITHUB_REF#refs/tags/v}"
+        git push origin master
+
+  update-docs:
+    name: Update documentation
+    needs: update-version
+    uses: ./.github/workflows/update_ghpages.yml

.github/workflows/ci_tests.yml

@@ -55,7 +55,7 @@ jobs:
     - name: Build documentation
       run: python docs/scripts/build.py ${PUBLISH_DOCS_DIR} && ls -lahR ${PUBLISH_DOCS_DIR}
 
-    - name: \"Publish\" ontologies
+    - name: '"Publish" ontologies'
       run: python .github/utils/publish_ontologies.py && ls -lahR ${PUBLISH_DOCS_DIR}
       env:
         PUBLISH_ONTOLOGIES_DIR: ontology

battinfo.ttl

@@ -12,7 +12,7 @@
 @base <https://big-map.github.io/BattINFO/ontology/BattINFO> .
 
 <https://big-map.github.io/BattINFO/ontology/BattINFO> rdf:type owl:Ontology ;
-                                                        owl:versionIRI <https://big-map.github.io/BattINFO/ontology/BattINFO/0.6.0/battinfo> ;
+                                                        owl:versionIRI <https://big-map.github.io/BattINFO/ontology/BattINFO/0.6.0/battinfo.ttl> ;
                                                         owl:imports <http://emmo.info/battery/0.6.0/battery-inferred> ;
                                                         dcterms:abstract """A battery interface domain ontology based on EMMO.
 This file is intended to be empty and merely collecting the other ontologies.

catalog-v001.xml

@@ -1,8 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
 	<group id="Folder Repository, directory=, recursive=true, Auto-Update=false, version=2" prefer="public" xml:base="">
-        <uri name="https://big-map.github.io/BattINFO/ontology/BattINFO/0.6.0/battinfo" uri="./battinfo.ttl"/>
-	<uri name="http://emmo.info/battery/0.6.0/battery-inferred"    			uri="https://raw.githubusercontent.com/emmo-repo/domain-battery/0.6.0/inferred_version/battery-inferred.ttl"/>
-
+        <uri name="https://big-map.github.io/BattINFO/ontology/BattINFO/0.6.0/battinfo.ttl" uri="./battinfo.ttl"/>
+	    <uri name="http://emmo.info/battery/0.6.0/battery-inferred" uri="https://raw.githubusercontent.com/emmo-repo/domain-battery/0.6.0/inferred_version/battery-inferred.ttl"/>
     </group>
 </catalog>

docs/scripts/publishing_docs.md

@@ -21,17 +21,38 @@ The contents of the dedicated folder is then merged into the `gh-pages` branch o
 
 By merging in the contents of the dedicated folder, the `gh-pages` branch will contain and preserve any old ontology versions that shouldn't be removed, while updating the documentation and adding any new ontology versions.
 
+### Building the documentation (locally)
 
-
-To build the documentation, run the following command from the root of the repository:
+To build the documentation locally, run the following command from the root of the repository:
 
 ```shell
-python docs/scripts/build_docs.py
+python docs/scripts/build.py site
 ```
 
+Now you can open the `index.html` file in the `site` folder to view the documentation.
+
 ## Publishing ontologies
 
-Publishing the ontologies means copying the Turtle (`.ttl`) files into an appropriate sub-folder of the `ontologies` folder in the `gh-pages` branch of the repository, along with a copy of the `catalog-v001.xml` file.
+Publishing the ontologies means copying the Turtle (`.ttl`) files into an appropriate sub-folder of the `ontology` folder in the `gh-pages` branch of the repository, along with a copy of the `catalog-v001.xml` file.
 This is done by the [`publish_ontologies.py`](../../.github/utils/publish_ontologies.py) script.
 
-To determine
+To determine the relative path to the sub-folder, the script uses the `owl:versionIRI` value to determine the version of the ontology.
+Then it creates the path `ontology/<ontology_top_name>/<version>/` and copies the Turtle files into it.
+If the ontology has a specific "sub"-name, e.g., `batteryquantities`, then the path will be `ontology/<ontology_top_name>/<version>/<sub_name>/`.
+
+For the core BattINFO ontology, the path should be `ontology/BattINFO/<version>/`.
+
+### Publishing ontologies (locally)
+
+To publish the ontologies locally, run the following command from the root of the repository:
+
+```shell
+python .github/utils/publish_ontologies.py
+```
+
+If one wishes to control the publication location further, one can set environment variables:
+
+| Environment variable | Description | Default value |
+| --- | --- | --- |
+| `PUBLISH_DOCS_DIR` | The path to the directory where the documentation should be published. This can be relative to the root of the repository or an absolute path. | `site` |
+| `PUBLISH_ONTOLOGIES_DIR` | The path to the directory where the ontologies should be published. This **must** be a relative path, relative to `PUBLISH_DOCS_DIR`. | `ontology` |

docs/scripts/releasing_new_version.md

@@ -0,0 +1,39 @@
+# Release a new BattINFO version
+
+## Introduction
+
+This document describes the process of releasing a new version of the BattINFO ontology.
+
+## Prerequisites
+
+To release a new version of the BattINFO ontology, you need to have:
+
+- A GitHub account with release creation access to the [BattINFO repository](https://github.com/BIG-MAP/BattINFO).
+
+## Release process
+
+The release process is as follows:
+
+1. [Create a new release on GitHub.](#create-a-new-release-on-github)
+2. [Check that the documentation is built and published correctly.](#check-that-the-documentation-is-built-and-published-correctly)
+
+### Create a new release on GitHub
+
+To create a new release on GitHub, follow these steps:
+
+1. Go to [create a new release in the BattINFO repository](https://github.com/BIG-MAP/BattINFO/releases/new).
+2. Set the tag version to the version you want to release, e.g., `v0.1.0`.
+3. Set the release title similarly, e.g., `v0.1.0`.
+4. Write a description of the release.
+
+### Check that the documentation is built and published correctly
+
+To check that the documentation is built and published correctly, follow these steps:
+
+1. Go to [the Actions tab in the BattINFO repository](https://github.com/BIG-MAP/BattINFO/actions).
+2. Click on the latest workflow run for the "Publish new release" workflow.
+3. Ensure it finishes successfully.
+
+If the workflow run finishes successfully, the version will be updated in the `owl:versionIRI` and `owl:versionInfo` values of the [`battinfo.ttl`](../../battinfo.ttl) file as well as in the [`catalog-v001.xml`](../../catalog-v001.xml) file.
+After these changes being merged back into the `master` branch, the documentation will be built and published to the `gh-pages` branch of the repository with the new version.
+This will be done by calling the [`update_ghpages.yml`](../../.github/workflows/update_ghpages.yml) workflow.