Skip to content

Contribution guide

CI

All pull-requests should pass CI, including linting and testing.

Linting (pre-commit)

We use pre-commit to ensure every commit reaches a minimum quality level. While it's not mandatory, it is strongly advised to install pre-commit hooks in your workspace to ensure that every commit will be automatically checked and/or formatted:

pre-commit install

You can run those linters on demand for tracked files:

pdm lint

Type checking is minimal in pre-commit so if you want to perform a full typing analysis, run:

pdm typing

Tests

Tests are managed using pytest. You can run them in your worksapce using:

pdm test

You can test against all supported Python versions using tox with:

pdm test:all

Documentation

The documentation is built using MkDocs with the mkdocs-ledger theme.

You can run a live development server locally using:

pdm doc:serve

If you rely on some services (like PlantUML Server for documentation generation), you can start them using Docker Compose with the doc profile:

docker compose up --profile doc

PlantUML

To benefit from the local PlantUML server, you also need to expose the PLANTUML_SERVER environment variable:

export PLANTUML_SERVER=http://localhost:8080
pdm doc:serve

If this variable is missing, it will fallback on the public http://www.plantuml.com/plantuml instance.

Conventional commit

We use conventional commit for commit messages.

Type must be one of the following:

  • build: Changes that affect the build system or external dependencies
  • ci: Changes to our CI configuration files and scripts (e.g. GitHub workflows)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes on code formatting that do not affect the meaning of the code
  • test: Adding missing tests or correcting existing tests