contributing.md

How to contribute

Prerequisites

Mandatory

• uv

Optional

• mise
• Pre-Commit
• shfmt
• shellcheck
• editorconfig-checker

Install the optional prerequisites

• If you installed mise, you can simply run:

mise install

Hack

• run make setup-venv so that uv inits a virtual environment with required dependencies (same as uv sync)

Update the dependencies

Run make upgrade-dependencies, this is the same as uv sync --upgrade.

Code

• run make test to launch unit tests
• run make lint to launch linters
• run make integration-tests to launch the integration tests

Documentation

• run make serve-docs to preview the documentation locally (live reload)
• run make build-docs to build the static site

The documentation is written with MkDocs and the Material theme, following the Diátaxis framework. It is published to GitHub Pages on every push to main.

Pre-Commit

• If you want to run pre-commit before each commit, run once make precommit-install
• If you don't want to configure a pre-commit hook (your choice, pre-commit is run by the CICD anyway), you can run it when you want, use make precommit-run

Configure your editor

VSCode

• It's a good idea to install the EditorConfig for VSCode extension
• Your settings.json (user or workspace or project) should contain:

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit",
      "source.fixAll": "explicit"
    }
  },
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.trimFinalNewlines": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestEnabled": true
}

Others

• Feel free to contribute any other editor configuration