Contribution guidelines

We would love that you contribute to Caliber! Please follow the regular GitHub workflow, i.e. fork the repo, commit changes to a new branch, and submit a pull request to suggest changes, or file issues directly on GitHub.

Set up your local development environment

We recommend to always use a virtual environment for your local development environment. To set up your virtual environment, type the following:

Caution

If it is the first time you initialize and activate a virtual environment on your computer, you should consider executing one line at a time to see the effect and to handle any exceptions that might be raised.

Hint

If you are using PowerShell, you might need to set the Execution Policy to be able to run the script that activates your virtual environment. Type the following to set an appropriate policy for the current user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Python launcher

py -m venv venv
venv\scripts\activate
py -m pip install uv
py -m uv pip install -r requirements.txt

Python

python -m venv venv
venv\scripts\activate
python -m pip install uv
python -m uv pip install -r requirements.txt

Note

We recommend using Python launcher for running Python on Windows, and uv as a drop-in replacement for pip.

Code format, linting and testing

Before creating a pull request, please make sure that your code runs without errors, that code formatting, linting and static type checking is ok, and that none of the tests break. Dependencies, formatting, linting, static type checking and testing are conveniently checked using the provided makefile. Have a look at this tutorial if you need a primer.

Hint

If you do not have make installed, you can install this using Chocolatey:

choco install make

However, you do not need to have make installed to run formatting, linting, static type checking, and testing. The necessary commands for each task are listed in the provided makefile.

Install dependencies:

With make

make deps

Without make

python -m pip install --upgrade uv
python -m uv pip install -r requirements.txt
python -m uv pip install tox tox-uv
python -m uv pip install --upgrade ruff
python -m uv pip install --upgrade mypy
python -m uv pip install --upgrade flit
python -m uv pip install --upgrade pytest pytest-cov

Note that make deps installs both the necessary dependencies for Caliber, and the developer tools that we rely on.

Check code format:

With make

make form

Without make

python -m ruff format caliber
python -m ruff format tests

Run linting and static type checking:

With make

make lint

Without make

python -m ruff check caliber
python -m ruff check tests
python -m mypy --config-file mypy.ini caliber

Run tests:

With make

make test

Without make

python -m pytest --junitxml=junit/test-results.xml --cov=caliber --cov-report=term-missing --cov-report=xml

Or all in one go if you start from a clean, activated virtual environment:

make deps form lint test

Automate checks across multiple Python versions with tox

We use tox to automate code formatting, linting, static type checking, and testing across multiple Python versions. See the provided tox.ini for an overview of the Python versions we are currently supporting.

Start by creating a virtual environment, if you have not already done so:

Python-launcher

py -m venv venv

Python

python -m venv venv

Activate the virtual environment and install dependencies:

venv\scripts\activate
make deps

To target a specific Python version, e.g. 3.11, type the following to run all checks:

Python-launcher

py -m tox -e py311

Python

python -m tox -e py311

To run all checks with all supported Python versions, type the following:

Python-launcher

py -m tox -e ALL

Python

python -m tox -e ALL