diff --git a/.github/utils/publish_ontologies.py b/.github/utils/publish_ontologies.py index ba80651..39487ac 100644 --- a/.github/utils/publish_ontologies.py +++ b/.github/utils/publish_ontologies.py @@ -46,21 +46,21 @@ class VersionIRI(str): """ _VERSION_IRI_REGEX = re.compile( - r"https?://(?P[a-zA-Z._-]+)/(?P[a-zA-Z_-]+(/[a-zA-Z_-]+)*)" - r"/(?P[0-9a-zA-Z._-]+)(/(?P[a-zA-Z_-]+))?(/(?P[a-zA-Z_.-]+))?" + r"https?://(?P[a-zA-Z._-]+)/(?P[a-zA-Z_-]+(?:/[a-zA-Z_-]+)*)" + r"/(?P[0-9a-zA-Z._-]+)(?:/(?P[a-zA-Z_-]+))?(?:/(?P[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: diff --git a/.github/workflows/cd_update_version.yml b/.github/workflows/cd_update_version.yml index 9047d20..afa3fa1 100644 --- a/.github/workflows/cd_update_version.yml +++ b/.github/workflows/cd_update_version.yml @@ -9,7 +9,8 @@ env: GIT_USER_EMAIL: "BattINFO@big-map.org" 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: | \ No newline at end of file + 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 diff --git a/.github/workflows/ci_tests.yml b/.github/workflows/ci_tests.yml index 88fbf86..e43458d 100644 --- a/.github/workflows/ci_tests.yml +++ b/.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 diff --git a/battinfo.ttl b/battinfo.ttl index 051df65..d40dea3 100644 --- a/battinfo.ttl +++ b/battinfo.ttl @@ -12,7 +12,7 @@ @base . rdf:type owl:Ontology ; - owl:versionIRI ; + owl:versionIRI ; owl:imports ; dcterms:abstract """A battery interface domain ontology based on EMMO. This file is intended to be empty and merely collecting the other ontologies. diff --git a/catalog-v001.xml b/catalog-v001.xml index 083bd2f..06a10c3 100644 --- a/catalog-v001.xml +++ b/catalog-v001.xml @@ -1,8 +1,7 @@ - - - + + diff --git a/docs/scripts/publishing_docs.md b/docs/scripts/publishing_docs.md index 67b64be..b3db01d 100644 --- a/docs/scripts/publishing_docs.md +++ b/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///` and copies the Turtle files into it. +If the ontology has a specific "sub"-name, e.g., `batteryquantities`, then the path will be `ontology////`. + +For the core BattINFO ontology, the path should be `ontology/BattINFO//`. + +### 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` | diff --git a/docs/scripts/releasing_new_version.md b/docs/scripts/releasing_new_version.md new file mode 100644 index 0000000..6fdc910 --- /dev/null +++ b/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.