[](https://www.repostatus.org/#active)
# Olivaw
An Agile methodology for ontology development named [ACIMOV](https://www.emse.fr/~zimmermann/Papers/mk2023.pdf) has been proposed in 2023.
This methodology is an extension of [SAMOD](https://essepuntato.it/samod/) with some improvements, including:
* the possibility to develop modular ontologies
* ensuring alignment to selected reference ontologies
* a wider collaboration between product owners, domain experts and ontology developers
This repository is a python library meant for providing tools in an Acimov ontology development context.
Olivaw proposes:
* command lines that make an Acimov development easier
* composite actions that can directly be called in workflows from any Acimov project
* a pre-commit hook that should prevent the biggest mistakes that could be pushed in an Acimov repository
The test reports are first represented using the [EARL vocabulary](https://www.w3.org/TR/EARL10-Schema/) and then exported in the markdown format.
Examples of reports generated from existing ontology projects can be found in the [olivaw reports examples](https://github.com/Wimmics/olivaw/blob/main/docs/examples/) folder.
A template repository also exist in order for an ontology project to begin with the accurate repository architecture, workflows, template special files (primee, code of conduct, contributing, etc) so check the [acimov olivaw repository template](https://github.com/Wimmics/Olivaw-Template).
In order to get all the available features in olivaw, check the [olivaw functional documentation](https://github.com/Wimmics/olivaw/blob/main/docs/).
Moreover the project, from the project structure itself to the details about any module, function and constants, is documented, so check the [olivaw technical documentation](https://github.com/Wimmics/olivaw/blob/main/olivaw/).
Olivaw proposes different test tools all powered by Corese, check [Corese website](https://project.inria.fr/corese/) and [Corese repository](https://github.com/Wimmics/corese).
Olivaw is affiliated to the [Wimmics reasearch team](https://www.inria.fr/fr/wimmics), check the other [Wimmics projects](https://github.com/Wimmics).
If a bug is to be found or a feature to be proposed, please use [olivaw issue menu](https://github.com/Wimmics/olivaw/issues).
# Getting started
## Installation requirements
Olivaw needs [python 3.10 or greater](https://www.python.org/downloads/) and [java version 11 or greater](https://www.java.com/en/download/manual.jsp).
Using a virtual environment would be a good idea, check [anaconda navigator](https://docs.anaconda.com/free/navigator/) or equivalent such as [miniconda](https://docs.anaconda.com/free/miniconda/) or [venv](https://pypi.org/project/virtualenv/).
## Installing olivaw in a project
First prepare a python environment version 3.8 or greater (3.11 if pre-commit hook is meant to be used).
Then install the library from [pipy](https://pypi.org/project/olivaw/):
```shell
pip install olivaw==0.0.5
```
It can also be installed using this command:
```shell
pip install git+https://github.com/Wimmics/olivaw@v0.0.5
```
## Intializing a repository
### Acimov repository structure
This tool is meant to work on an Acimov structured repository.
The [acimov olivaw repository template](https://github.com/Wimmics/Olivaw-Template) can be used to create a new project or be used to adapt an existing project to this structure.
This repository contains:
* the folders:
* `.acimov/`
* `resources/`
* `primer/`
* `src/`
* `domains/`
* `use-cases/`
* a `README.md` file at the root folder
### Getting a personnal access token with gist scope
This framework proposes automatically updated badges at the top of the README.md on each branch.
To make this work a personnal access token with the `gist` scope is required.
* First go to the [Github access token generation webpage](https://github.com/settings/tokens).
* Then create a personnal access token with only the `gist` scope. Copy/paste this token somewhere because it will never be shown again.
* Then go to `{repository_url}/settings/secrets/actions`, create a new repository secret named `GIST_SECRET` and paste the key
### Initialize repository parameters
Finally this library needs a `parameters.json` file in the `.acimov/` folder that should contain parameters related to the repository.
Use this command to generate one:
```shell
olivaw init repo
```
Just follow the instructions (the personnal access token with `gist` scope will be asked again).
After the execution of the command file named `parameters.json` in the `.acimov/` folder should have appeared and also badges added to the top of the repository `README.md` file with an initialized gist on [gist website](https://gist.github.com/).
These parameters can eventually be customized using the [olivaw parameters documentation](https://github.com/Wimmics/olivaw/blob/main/docs/parameters.md).
The olivaw commands are now available inside the repository!
# Basics about olivaw
There are three usages of olivaw that are complementary:
* the [command](#the-command-line) line allows the developper to run tests on client side on demand and provides tools for everyday development
* the [actions](#the-github-actions) can regularly make a health check of a branch on server side and manage the project badges
* the [pre-commit](#the-pre-commit-hook) hook can test on client side a commit and block it if a blocking error is to be found in the staged files
## The command line
Here is only a short overview of the main commands. Check the [olivaw command line documentation](https://github.com/Wimmics/olivaw/blob/main/docs/commands.md) for more details about the available commands.
### Model test
Anywhere in the repository use this command to launch a model test:
```shell
olivaw test model
```
### Data test
This command is for launching data test
```shell
olivaw test data
```
### Query test
This command is for launching query test
```shell
olivaw test query
```
## The Github actions
Here is an overview of the actions available. For more details see the [olivaw Github Actions documentation](https://github.com/Wimmics/olivaw/blob/main/docs/actions.md).
Each actions of this chapter involve to create a `.yaml` file located in `{repository_path}/.github/workflows/`.
### Automatic tests on push
In `./github/worflows/` folder, add a `test.yaml` file containing this:
```yaml
name: test
on: push
jobs:
test:
permissions:
contents: write
runs-on: ubuntu-latest
steps:
- uses: Wimmics/olivaw/test-actions@v0.0.5
with:
repository: ${{ github.repository }}
ref: ${{ github.ref }}
gist-secret: ${{ secrets.GIST_SECRET }}
```
Then, after each push on the repository an actions will be triggered and after some time, in the `.acimov/output/` folder should have appeared:
* RDF files written in the turtle format representing the result of the test, written with the EARL vocabulary
* markdown files representing in a human readable way the previous turtle files
### Badges branch initialization
In `./github/worflows/` folder, add a `init-branch.yaml` file containing this:
```yaml
name: init-branch
on: create
jobs:
model-test:
permissions:
contents: write
runs-on: ubuntu-latest
steps:
- uses: Wimmics/olivaw/init-branch@v0.0.5
with:
repository: ${{ github.repository }}
ref: ${{ github.ref }}
gist-secret: ${{ secrets.GIST_SECRET }}
```
Then on each time a branch is published, the actions should create new gists and update the badges in the README.md without anything left to do for the developper.
## The pre-commit hook
[Pre-commit](https://pre-commit.com/) is a framework that allows on client side to connect programs to git events such as commit, push, merge, etc.
A pre-commit hook is available in this repository to prevent the developper to push big mistakes on the server.
To use it should need first need to install pre-commit. Create a fresh new python 3.11 environment for the tool to work properly.
Once the new environment set, install pre-commit with this command:
```shell
pip install pre-commit
```
Then add a file named `.pre-commit-config.yaml` at the root of the repository containing this:
```yaml
default_language_version:
python: python3
repos:
- repo: https://github.com/Wimmics/olivaw
rev: v0.0.5
hooks:
- id: olivaw-test
```
Then use this command at the root of the repository:
```shell
pre-commit install
```
Finally add the `.pre-commit-config.yaml` file to the commit:
```turtle
git add .pre-commit-config.yaml
```
Now, each time a commit is made, the staged files will be tested and the commit will be blocked if any blocking error is to be found in any of those files.
The test takes a few seconds and pre-commit needs a moment to prepare the hook on the very first use.
There is also the [olivaw pre-commit hook documentation](https://github.com/Wimmics/olivaw/blob/main/docs/pre-commit.md).
# Citation
This repository is one result of the [hMAS ontology project](https://github.com/HyperAgents/hmas) and therefore a part of [HyperAgents ANR/SNF project](https://www.hyperagents.org/). Check the [contributors file](https://github.com/Wimmics/olivaw/blob/main/CONTRIBUTORS.md) of the project.
Please cite as the GitHub repository metadata proposes and/or check the [citation file](https://github.com/Wimmics/olivaw/blob/main/CITATION.cff).
# Contributing / report an issue
Don't hesitate to [report an issue](https://github.com/Wimmics/olivaw/issues) or [make a pull request](https://github.com/Wimmics/olivaw/pulls) at will.
Raw data
{
"_id": null,
"home_page": "https://github.com/Wimmics/olivaw",
"name": "olivaw",
"maintainer": "Nicolas Robert",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "nicolas_robert_31@hotmail.fr",
"keywords": "semantics, ontology, schema, vocabulary, linked data, validation, RDF, RDFS, OWL, SHACL, SPARQL",
"author": "Nicolas Robert",
"author_email": "nicolas_robert_31@hotmail.fr",
"download_url": "https://pypi.org/project/olivaw/",
"platform": null,
"description": "[](https://www.repostatus.org/#active)\r\n# Olivaw\r\n\r\nAn Agile methodology for ontology development named [ACIMOV](https://www.emse.fr/~zimmermann/Papers/mk2023.pdf) has been proposed in 2023.\r\n\r\nThis methodology is an extension of [SAMOD](https://essepuntato.it/samod/) with some improvements, including:\r\n\r\n* the possibility to develop modular ontologies\r\n* ensuring alignment to selected reference ontologies\r\n* a wider collaboration between product owners, domain experts and ontology developers\r\n\r\nThis repository is a python library meant for providing tools in an Acimov ontology development context.\r\n\r\nOlivaw proposes:\r\n\r\n* command lines that make an Acimov development easier\r\n* composite actions that can directly be called in workflows from any Acimov project\r\n* a pre-commit hook that should prevent the biggest mistakes that could be pushed in an Acimov repository\r\n\r\nThe test reports are first represented using the [EARL vocabulary](https://www.w3.org/TR/EARL10-Schema/) and then exported in the markdown format.\r\n\r\nExamples of reports generated from existing ontology projects can be found in the [olivaw reports examples](https://github.com/Wimmics/olivaw/blob/main/docs/examples/) folder.\r\n\r\nA template repository also exist in order for an ontology project to begin with the accurate repository architecture, workflows, template special files (primee, code of conduct, contributing, etc) so check the [acimov olivaw repository template](https://github.com/Wimmics/Olivaw-Template).\r\n\r\nIn order to get all the available features in olivaw, check the [olivaw functional documentation](https://github.com/Wimmics/olivaw/blob/main/docs/).\r\n\r\nMoreover the project, from the project structure itself to the details about any module, function and constants, is documented, so check the [olivaw technical documentation](https://github.com/Wimmics/olivaw/blob/main/olivaw/).\r\n\r\nOlivaw proposes different test tools all powered by Corese, check [Corese website](https://project.inria.fr/corese/) and [Corese repository](https://github.com/Wimmics/corese).\r\n\r\nOlivaw is affiliated to the [Wimmics reasearch team](https://www.inria.fr/fr/wimmics), check the other [Wimmics projects](https://github.com/Wimmics).\r\n\r\nIf a bug is to be found or a feature to be proposed, please use [olivaw issue menu](https://github.com/Wimmics/olivaw/issues).\r\n\r\n# Getting started\r\n\r\n## Installation requirements\r\n\r\nOlivaw needs [python 3.10 or greater](https://www.python.org/downloads/) and [java version 11 or greater](https://www.java.com/en/download/manual.jsp).\r\n\r\nUsing a virtual environment would be a good idea, check [anaconda navigator](https://docs.anaconda.com/free/navigator/) or equivalent such as [miniconda](https://docs.anaconda.com/free/miniconda/) or [venv](https://pypi.org/project/virtualenv/).\r\n\r\n## Installing olivaw in a project\r\n\r\nFirst prepare a python environment version 3.8 or greater (3.11 if pre-commit hook is meant to be used).\r\n\r\nThen install the library from [pipy](https://pypi.org/project/olivaw/):\r\n\r\n```shell\r\npip install olivaw==0.0.5\r\n```\r\n\r\nIt can also be installed using this command:\r\n\r\n```shell\r\npip install git+https://github.com/Wimmics/olivaw@v0.0.5\r\n```\r\n\r\n## Intializing a repository\r\n\r\n### Acimov repository structure\r\n\r\nThis tool is meant to work on an Acimov structured repository.\r\n\r\nThe [acimov olivaw repository template](https://github.com/Wimmics/Olivaw-Template) can be used to create a new project or be used to adapt an existing project to this structure.\r\n\r\nThis repository contains:\r\n\r\n* the folders:\r\n * `.acimov/`\r\n * `resources/`\r\n * `primer/`\r\n * `src/`\r\n * `domains/`\r\n * `use-cases/`\r\n* a `README.md` file at the root folder\r\n\r\n### Getting a personnal access token with gist scope\r\n\r\nThis framework proposes automatically updated badges at the top of the README.md on each branch.\r\n\r\nTo make this work a personnal access token with the `gist` scope is required.\r\n\r\n* First go to the [Github access token generation webpage](https://github.com/settings/tokens).\r\n* Then create a personnal access token with only the `gist` scope. Copy/paste this token somewhere because it will never be shown again.\r\n* Then go to `{repository_url}/settings/secrets/actions`, create a new repository secret named `GIST_SECRET` and paste the key\r\n\r\n### Initialize repository parameters\r\n\r\nFinally this library needs a `parameters.json` file in the `.acimov/` folder that should contain parameters related to the repository.\r\n\r\nUse this command to generate one:\r\n\r\n```shell\r\nolivaw init repo\r\n```\r\n\r\nJust follow the instructions (the personnal access token with `gist` scope will be asked again).\r\n\r\nAfter the execution of the command file named `parameters.json` in the `.acimov/` folder should have appeared and also badges added to the top of the repository `README.md` file with an initialized gist on [gist website](https://gist.github.com/).\r\n\r\nThese parameters can eventually be customized using the [olivaw parameters documentation](https://github.com/Wimmics/olivaw/blob/main/docs/parameters.md).\r\n\r\nThe olivaw commands are now available inside the repository!\r\n\r\n# Basics about olivaw\r\n\r\nThere are three usages of olivaw that are complementary:\r\n\r\n* the [command](#the-command-line) line allows the developper to run tests on client side on demand and provides tools for everyday development\r\n* the [actions](#the-github-actions) can regularly make a health check of a branch on server side and manage the project badges\r\n* the [pre-commit](#the-pre-commit-hook) hook can test on client side a commit and block it if a blocking error is to be found in the staged files\r\n\r\n## The command line\r\n\r\nHere is only a short overview of the main commands. Check the [olivaw command line documentation](https://github.com/Wimmics/olivaw/blob/main/docs/commands.md) for more details about the available commands.\r\n\r\n### Model test\r\n\r\nAnywhere in the repository use this command to launch a model test:\r\n\r\n```shell\r\nolivaw test model\r\n```\r\n\r\n### Data test\r\n\r\nThis command is for launching data test\r\n\r\n```shell\r\nolivaw test data\r\n```\r\n\r\n### Query test\r\n\r\nThis command is for launching query test\r\n\r\n```shell\r\nolivaw test query\r\n```\r\n\r\n## The Github actions\r\n\r\nHere is an overview of the actions available. For more details see the [olivaw Github Actions documentation](https://github.com/Wimmics/olivaw/blob/main/docs/actions.md).\r\n\r\nEach actions of this chapter involve to create a `.yaml` file located in `{repository_path}/.github/workflows/`.\r\n\r\n### Automatic tests on push\r\n\r\nIn `./github/worflows/` folder, add a `test.yaml` file containing this:\r\n\r\n```yaml\r\nname: test\r\non: push\r\n\r\njobs:\r\n test:\r\n permissions:\r\n contents: write\r\n runs-on: ubuntu-latest\r\n steps:\r\n - uses: Wimmics/olivaw/test-actions@v0.0.5\r\n with:\r\n repository: ${{ github.repository }}\r\n ref: ${{ github.ref }}\r\n gist-secret: ${{ secrets.GIST_SECRET }}\r\n```\r\n\r\nThen, after each push on the repository an actions will be triggered and after some time, in the `.acimov/output/` folder should have appeared:\r\n\r\n* RDF files written in the turtle format representing the result of the test, written with the EARL vocabulary\r\n* markdown files representing in a human readable way the previous turtle files\r\n\r\n### Badges branch initialization\r\n\r\nIn `./github/worflows/` folder, add a `init-branch.yaml` file containing this:\r\n\r\n```yaml\r\nname: init-branch\r\non: create\r\n\r\njobs:\r\n model-test:\r\n permissions:\r\n contents: write\r\n runs-on: ubuntu-latest\r\n steps:\r\n - uses: Wimmics/olivaw/init-branch@v0.0.5\r\n with:\r\n repository: ${{ github.repository }}\r\n ref: ${{ github.ref }}\r\n gist-secret: ${{ secrets.GIST_SECRET }}\r\n```\r\n\r\nThen on each time a branch is published, the actions should create new gists and update the badges in the README.md without anything left to do for the developper.\r\n\r\n## The pre-commit hook\r\n\r\n[Pre-commit](https://pre-commit.com/) is a framework that allows on client side to connect programs to git events such as commit, push, merge, etc. \r\n\r\nA pre-commit hook is available in this repository to prevent the developper to push big mistakes on the server.\r\n\r\nTo use it should need first need to install pre-commit. Create a fresh new python 3.11 environment for the tool to work properly.\r\n\r\nOnce the new environment set, install pre-commit with this command:\r\n\r\n```shell\r\npip install pre-commit\r\n```\r\n\r\nThen add a file named `.pre-commit-config.yaml` at the root of the repository containing this:\r\n\r\n```yaml\r\ndefault_language_version:\r\n python: python3\r\nrepos:\r\n- repo: https://github.com/Wimmics/olivaw\r\n rev: v0.0.5\r\n hooks:\r\n - id: olivaw-test\r\n```\r\n\r\nThen use this command at the root of the repository:\r\n\r\n```shell\r\npre-commit install\r\n```\r\n\r\nFinally add the `.pre-commit-config.yaml` file to the commit:\r\n\r\n```turtle\r\ngit add .pre-commit-config.yaml\r\n```\r\n\r\nNow, each time a commit is made, the staged files will be tested and the commit will be blocked if any blocking error is to be found in any of those files.\r\n\r\nThe test takes a few seconds and pre-commit needs a moment to prepare the hook on the very first use.\r\n\r\nThere is also the [olivaw pre-commit hook documentation](https://github.com/Wimmics/olivaw/blob/main/docs/pre-commit.md).\r\n\r\n# Citation\r\n\r\nThis repository is one result of the [hMAS ontology project](https://github.com/HyperAgents/hmas) and therefore a part of [HyperAgents ANR/SNF project](https://www.hyperagents.org/). Check the [contributors file](https://github.com/Wimmics/olivaw/blob/main/CONTRIBUTORS.md) of the project.\r\n\r\nPlease cite as the GitHub repository metadata proposes and/or check the [citation file](https://github.com/Wimmics/olivaw/blob/main/CITATION.cff).\r\n\r\n# Contributing / report an issue\r\n\r\nDon't hesitate to [report an issue](https://github.com/Wimmics/olivaw/issues) or [make a pull request](https://github.com/Wimmics/olivaw/pulls) at will.\r\n",
"bugtrack_url": null,
"license": "LGPL-2.1",
"summary": "Python framework for supporting agile ontology development",
"version": "0.0.5",
"project_urls": {
"Download": "https://pypi.org/project/olivaw/",
"Homepage": "https://github.com/Wimmics/olivaw"
},
"split_keywords": [
"semantics",
" ontology",
" schema",
" vocabulary",
" linked data",
" validation",
" rdf",
" rdfs",
" owl",
" shacl",
" sparql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d90f7094c8541566b0892869a38a825f13bd55fddab2b2512e26e8e3e23000d9",
"md5": "9e3f2472c0ba9a8a2fdf53618fc16fbd",
"sha256": "71ead860e159366ffab582c814ff26e667f4cfabdeec7a8db9922a92f5f4fd79"
},
"downloads": -1,
"filename": "olivaw-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e3f2472c0ba9a8a2fdf53618fc16fbd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 27721216,
"upload_time": "2024-06-13T19:51:06",
"upload_time_iso_8601": "2024-06-13T19:51:06.253877Z",
"url": "https://files.pythonhosted.org/packages/d9/0f/7094c8541566b0892869a38a825f13bd55fddab2b2512e26e8e3e23000d9/olivaw-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-13 19:51:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Wimmics",
"github_project": "olivaw",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "olivaw"
}
JSON
