diff --git a/.github/workflows/check-generated-files.yml b/.github/workflows/check-generated-files.yml new file mode 100644 index 0000000..a247b7a --- /dev/null +++ b/.github/workflows/check-generated-files.yml @@ -0,0 +1,23 @@ +name: Check generated files + +on: + pull_request: + push: + branches: + - main + +jobs: + check-generated: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run generation script + run: scripts/github_generate.sh + + - name: Check for uncommitted changes + run: git diff --exit-code diff --git a/scripts/contributing/build_docs.md b/scripts/contributing/build_docs.md new file mode 100644 index 0000000..d8be0ff --- /dev/null +++ b/scripts/contributing/build_docs.md @@ -0,0 +1,23 @@ +## Build documentation + +The documentation is built with [Sphinx](https://www.sphinx-doc.org/en/master/) that generates HTML pages out of the RST files. The configuration of Sphinx is in `doc/conf.py`. + +Requirements (including Sphinx) can be installed with + +```bash +pip install .[doc] +``` + +Then, build the documentation with + +```bash +sphinx-build doc build/sphinx/html -E -a +``` + +The generated HTML pages will be available in `build/sphinx/html`. You can browse them by opening `build/sphinx/html/index.html` in your browser. + +When rebuilding the documentation, don't forget to remove generated files to have a fresh `autodoc` documentation: + +```bash +rm -rf doc/_generated/; sphinx-build doc build/sphinx/html -E -a +``` diff --git a/scripts/contributing/formatting_black.md b/scripts/contributing/formatting_black.md new file mode 100644 index 0000000..3005fb6 --- /dev/null +++ b/scripts/contributing/formatting_black.md @@ -0,0 +1,5 @@ +## Formatting + +All code must be formatted with [black](https://black.readthedocs.io/en/stable) latest version or the CI will break. Editor integration such as [Black VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) or [Git hooks](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) can be set-up for automatic formatting. + +The configuration can be found in `pyproject.toml`. diff --git a/scripts/contributing/formatting_ruff.md b/scripts/contributing/formatting_ruff.md new file mode 100644 index 0000000..2090fe6 --- /dev/null +++ b/scripts/contributing/formatting_ruff.md @@ -0,0 +1,7 @@ +## Formatting + +[ruff](https://docs.astral.sh/ruff/) is used to format the code. It gives formatting equivalent to [black](https://docs.astral.sh/ruff/faq/#how-does-ruffs-formatter-compare-to-black). + +Editor integration such as [Ruff VSCode extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) or [Git hooks](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) can be set-up for automatic formatting. + +The configuration can be found in `pyproject.toml` under `[tool.ruff.format]` sections. diff --git a/scripts/contributing/getting_started.md b/scripts/contributing/getting_started.md new file mode 100644 index 0000000..79a0fcb --- /dev/null +++ b/scripts/contributing/getting_started.md @@ -0,0 +1,7 @@ +## Getting started + +Requirements are listed in `pyproject.toml` and can be installed with + +```bash +pip install [--user] .[dev] +``` diff --git a/scripts/contributing/imports_isort.md b/scripts/contributing/imports_isort.md new file mode 100644 index 0000000..a123ec6 --- /dev/null +++ b/scripts/contributing/imports_isort.md @@ -0,0 +1,5 @@ +## Import order + +Order of imports is enforced by [isort](https://pycqa.github.io/isort/). Same as for black, editor extensions such as [isort VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.isort) can be used to sort imports automatically when saving. + +The configuration in `pyproject.toml` is made to be [compatible with black](https://pycqa.github.io/isort/docs/configuration/black_compatibility.html). diff --git a/scripts/contributing/imports_ruff.md b/scripts/contributing/imports_ruff.md new file mode 100644 index 0000000..e68d915 --- /dev/null +++ b/scripts/contributing/imports_ruff.md @@ -0,0 +1,12 @@ +## Import order + +Order of imports is enforced by [ruff](https://docs.astral.sh/ruff/) **linter**. The [imports can be automatically sorted](https://docs.astral.sh/ruff/formatter/#sorting-imports) by running: + +```bash +ruff check --select I --fix +ruff format +``` + +As for formatting, we advise to use the [Ruff VSCode extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) or [a Git hook](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) to sort imports automatically when saving. + +Configuration can be found in `pyproject.toml` under `[tool.ruff.lint.isort]` sections. diff --git a/scripts/contributing/linting_flake8.md b/scripts/contributing/linting_flake8.md new file mode 100644 index 0000000..97b9db3 --- /dev/null +++ b/scripts/contributing/linting_flake8.md @@ -0,0 +1,5 @@ +## Linting + +[flake8](https://flake8.pycqa.org/en/latest/index.html) is used to lint the code. + +The configuration is located in `.flake8`. It is written specifically to be compatible with black so that changes should not be needed. If needed, linting errors can be [ignored inline by adding comments](https://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors) (e.g.`# noqa: E123`). diff --git a/scripts/contributing/linting_ruff.md b/scripts/contributing/linting_ruff.md new file mode 100644 index 0000000..709453a --- /dev/null +++ b/scripts/contributing/linting_ruff.md @@ -0,0 +1,5 @@ +## Linting + +[ruff](https://docs.astral.sh/ruff/) is used to lint the code. The linting is equivalent to [flake8](https://docs.astral.sh/ruff/faq/#how-does-ruffs-linter-compare-to-flake8) linting. + +[Configuration](https://docs.astral.sh/ruff/configuration/) can be changed in `pyproject.toml` but the default configuration is compatible with black so that changes should not be needed. If needed, linting errors can be [ignored inline by adding comments](https://docs.astral.sh/ruff/linter/#line-level) (e.g.`# noqa: E123`). diff --git a/scripts/contributing/releasing.md b/scripts/contributing/releasing.md new file mode 100644 index 0000000..7ea7847 --- /dev/null +++ b/scripts/contributing/releasing.md @@ -0,0 +1,43 @@ +## Releasing + +1. Checkout `main` and verify that it is up to date with the server and that your working tree is clean. + +1. Add the [changes](https://changelog.md) to `CHANGELOG.md` under a version number that matches the + [regex pattern](https://regex101.com/r/Ly7O1x/3/) provided by the [semantic versioning](https://semver.org) + guidelines. For example the lifecycle of a single version could be + + ``` + 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0 + ``` + +1. Change the version number in `/pyproject.toml` to the version number put in the CHANGELOG. + +1. Push your changes to a branch and create a MR to merge your changes in `main`. + +1. Deploy the project using one of the two methods below: + + - Deploy through CI jobs (recommended) + + Once the tests have passed on `main`, CI jobs for deployment on [pypi](https://pypi.org) and [testpypi](https://test.pypi.org) + will be available in the CI pipeline page. Launching these jobs manually will trigger the deployment on the corresponding + python package index. In case of the `pypi` job a git tag for the version will be added to the repository. + + - Deploy manually from the terminal with `build` and `twine` + + ```bash + rm -rf dist + pip install build + python3 -m build -s + twine upload -r testpypi dist/* + twine upload -r pypi dist/* + ``` + +1. A git tag for the version is created automatically when deploying through the `pypi` CI job. Manual deployment however + requires manual tagging + + ```bash + git tag v1.2.3 + git push && git push --tags + ``` + + Release notes can be added in the `Tags` page of the gitlab repository. diff --git a/scripts/contributing/testing.md b/scripts/contributing/testing.md new file mode 100644 index 0000000..b163058 --- /dev/null +++ b/scripts/contributing/testing.md @@ -0,0 +1,13 @@ +## Testing + +Tests make use [pytest](https://docs.pytest.org/en/stable/index.html) and can be run as follows + +```bash +pytest . +``` + +Testing an installed project is done like this + +```bash +pytest --pyargs +``` diff --git a/scripts/contributing/write_docs.md b/scripts/contributing/write_docs.md new file mode 100644 index 0000000..eb73932 --- /dev/null +++ b/scripts/contributing/write_docs.md @@ -0,0 +1,5 @@ +## Write documentation + +The documentation is composed of RST files located in `doc`. You can look at the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) for information on how to write RST files. + +If a new file is created, don't forget to reference it in one of the `toctree` directive. diff --git a/scripts/github_contributing.py b/scripts/github_contributing.py new file mode 100644 index 0000000..0344f4f --- /dev/null +++ b/scripts/github_contributing.py @@ -0,0 +1,60 @@ +from pathlib import Path + +if __name__ == "__main__": + + thisdir = Path(__file__).parent + + sections = thisdir / "contributing" + + GETTING_STARTED = (sections / "getting_started.md").read_text() + TESTING = (sections / "testing.md").read_text() + WRITE_DOCS = (sections / "write_docs.md").read_text() + BUILD_DOCS = (sections / "build_docs.md").read_text() + RELEASING = (sections / "releasing.md").read_text() + + FORMATTING_BLACK = (sections / "formatting_black.md").read_text() + LINTING_FLAKE8 = (sections / "linting_flake8.md").read_text() + IMPORTS_ISORT = (sections / "imports_isort.md").read_text() + + FORMATTING_RUFF = (sections / "formatting_ruff.md").read_text() + LINTING_RUFF = (sections / "linting_ruff.md").read_text() + IMPORTS_RUFF = (sections / "imports_ruff.md").read_text() + + default_contributing = ( + GETTING_STARTED + + "\n" + + FORMATTING_BLACK + + "\n" + + LINTING_FLAKE8 + + "\n" + + IMPORTS_ISORT + + "\n" + + TESTING + + "\n" + + WRITE_DOCS + + "\n" + + BUILD_DOCS + + "\n" + + RELEASING + ) + + ruff_contributing = ( + GETTING_STARTED + + "\n" + + FORMATTING_RUFF + + "\n" + + LINTING_RUFF + + "\n" + + IMPORTS_RUFF + + "\n" + + TESTING + + "\n" + + WRITE_DOCS + + "\n" + + BUILD_DOCS + + "\n" + + RELEASING + ) + + (thisdir.parent / "shared" / "CONTRIBUTING.md").write_text(default_contributing) + (thisdir.parent / "shared" / "CONTRIBUTING_ruff.md").write_text(ruff_contributing) diff --git a/scripts/github_generate.sh b/scripts/github_generate.sh new file mode 100755 index 0000000..c0b69bf --- /dev/null +++ b/scripts/github_generate.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +python ./scripts/github_contributing.py diff --git a/shared/CONTRIBUTING.md b/shared/CONTRIBUTING.md index 3f2d42a..643a678 100644 --- a/shared/CONTRIBUTING.md +++ b/shared/CONTRIBUTING.md @@ -3,18 +3,18 @@ Requirements are listed in `pyproject.toml` and can be installed with ```bash -pip install .[dev] +pip install [--user] .[dev] ``` ## Formatting All code must be formatted with [black](https://black.readthedocs.io/en/stable) latest version or the CI will break. Editor integration such as [Black VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) or [Git hooks](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) can be set-up for automatic formatting. -The configuration can be found in `pyproject.toml`. +The configuration can be found in `pyproject.toml`. ## Linting -[flake8](https://flake8.pycqa.org/en/latest/index.html) is used to lint the code. +[flake8](https://flake8.pycqa.org/en/latest/index.html) is used to lint the code. The configuration is located in `.flake8`. It is written specifically to be compatible with black so that changes should not be needed. If needed, linting errors can be [ignored inline by adding comments](https://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors) (e.g.`# noqa: E123`). @@ -22,7 +22,7 @@ The configuration is located in `.flake8`. It is written specifically to be comp Order of imports is enforced by [isort](https://pycqa.github.io/isort/). Same as for black, editor extensions such as [isort VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.isort) can be used to sort imports automatically when saving. -The configuration in `pyproject.toml` is made to be [compatible with black](https://pycqa.github.io/isort/docs/configuration/black_compatibility.html). +The configuration in `pyproject.toml` is made to be [compatible with black](https://pycqa.github.io/isort/docs/configuration/black_compatibility.html). ## Testing @@ -88,9 +88,9 @@ rm -rf doc/_generated/; sphinx-build doc build/sphinx/html -E -a - Deploy through CI jobs (recommended) - Launch the `Release` pipeline can manually confirm the steps for - deployment on [pypi](https://pypi.org) and [testpypi](https://test.pypi.org) - When the `pypi` job succeeds a git tag for the version will be added to the repository. + Once the tests have passed on `main`, CI jobs for deployment on [pypi](https://pypi.org) and [testpypi](https://test.pypi.org) + will be available in the CI pipeline page. Launching these jobs manually will trigger the deployment on the corresponding + python package index. In case of the `pypi` job a git tag for the version will be added to the repository. - Deploy manually from the terminal with `build` and `twine` @@ -109,3 +109,5 @@ rm -rf doc/_generated/; sphinx-build doc build/sphinx/html -E -a git tag v1.2.3 git push && git push --tags ``` + + Release notes can be added in the `Tags` page of the gitlab repository. diff --git a/shared/CONTRIBUTING_ruff.md b/shared/CONTRIBUTING_ruff.md new file mode 100644 index 0000000..a46ab26 --- /dev/null +++ b/shared/CONTRIBUTING_ruff.md @@ -0,0 +1,122 @@ +## Getting started + +Requirements are listed in `pyproject.toml` and can be installed with + +```bash +pip install [--user] .[dev] +``` + +## Formatting + +[ruff](https://docs.astral.sh/ruff/) is used to format the code. It gives formatting equivalent to [black](https://docs.astral.sh/ruff/faq/#how-does-ruffs-formatter-compare-to-black). + +Editor integration such as [Ruff VSCode extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) or [Git hooks](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) can be set-up for automatic formatting. + +The configuration can be found in `pyproject.toml` under `[tool.ruff.format]` sections. + +## Linting + +[ruff](https://docs.astral.sh/ruff/) is used to lint the code. The linting is equivalent to [flake8](https://docs.astral.sh/ruff/faq/#how-does-ruffs-linter-compare-to-flake8) linting. + +[Configuration](https://docs.astral.sh/ruff/configuration/) can be changed in `pyproject.toml` but the default configuration is compatible with black so that changes should not be needed. If needed, linting errors can be [ignored inline by adding comments](https://docs.astral.sh/ruff/linter/#line-level) (e.g.`# noqa: E123`). + +## Import order + +Order of imports is enforced by [ruff](https://docs.astral.sh/ruff/) **linter**. The [imports can be automatically sorted](https://docs.astral.sh/ruff/formatter/#sorting-imports) by running: + +```bash +ruff check --select I --fix +ruff format +``` + +As for formatting, we advise to use the [Ruff VSCode extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) or [a Git hook](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks) to sort imports automatically when saving. + +Configuration can be found in `pyproject.toml` under `[tool.ruff.lint.isort]` sections. + +## Testing + +Tests make use [pytest](https://docs.pytest.org/en/stable/index.html) and can be run as follows + +```bash +pytest . +``` + +Testing an installed project is done like this + +```bash +pytest --pyargs +``` + +## Write documentation + +The documentation is composed of RST files located in `doc`. You can look at the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) for information on how to write RST files. + +If a new file is created, don't forget to reference it in one of the `toctree` directive. + +## Build documentation + +The documentation is built with [Sphinx](https://www.sphinx-doc.org/en/master/) that generates HTML pages out of the RST files. The configuration of Sphinx is in `doc/conf.py`. + +Requirements (including Sphinx) can be installed with + +```bash +pip install .[doc] +``` + +Then, build the documentation with + +```bash +sphinx-build doc build/sphinx/html -E -a +``` + +The generated HTML pages will be available in `build/sphinx/html`. You can browse them by opening `build/sphinx/html/index.html` in your browser. + +When rebuilding the documentation, don't forget to remove generated files to have a fresh `autodoc` documentation: + +```bash +rm -rf doc/_generated/; sphinx-build doc build/sphinx/html -E -a +``` + +## Releasing + +1. Checkout `main` and verify that it is up to date with the server and that your working tree is clean. + +1. Add the [changes](https://changelog.md) to `CHANGELOG.md` under a version number that matches the + [regex pattern](https://regex101.com/r/Ly7O1x/3/) provided by the [semantic versioning](https://semver.org) + guidelines. For example the lifecycle of a single version could be + + ``` + 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0 + ``` + +1. Change the version number in `/pyproject.toml` to the version number put in the CHANGELOG. + +1. Push your changes to a branch and create a MR to merge your changes in `main`. + +1. Deploy the project using one of the two methods below: + + - Deploy through CI jobs (recommended) + + Once the tests have passed on `main`, CI jobs for deployment on [pypi](https://pypi.org) and [testpypi](https://test.pypi.org) + will be available in the CI pipeline page. Launching these jobs manually will trigger the deployment on the corresponding + python package index. In case of the `pypi` job a git tag for the version will be added to the repository. + + - Deploy manually from the terminal with `build` and `twine` + + ```bash + rm -rf dist + pip install build + python3 -m build -s + twine upload -r testpypi dist/* + twine upload -r pypi dist/* + ``` + +1. A git tag for the version is created automatically when deploying through the `pypi` CI job. Manual deployment however + requires manual tagging + + ```bash + git tag v1.2.3 + git push && git push --tags + ``` + + Release notes can be added in the `Tags` page of the gitlab repository.