Development Setup

Below follow some explanations on what initial setup needs to be done when one wants to develop and contribute to a code base.

Machine-Wide Setup

The fundamental requirements for any development machine include:

• git,
• Python, and
• some way of managing virtual environments.

One great way of managing both Python and virtual environments is to use the amazing tool uv. In this document, we will assume you have uv installed.

Tip

Additionally, we strongly recommend you use ruff as a linter during your coding sessions. ruff is a fast and highly configurable linter that can help you maintain code quality and style consistency.

Additionally, a broad set of ruff's rules are enforced by our pre-commit hooks, so it might make sense to catch a good number of issues before you try to commit your code (and then fail the pre-commit checks).

Check out ruff's website to see how to install it and configure it for your editor of choice. Most editors have great support for ruff, and it can be easily integrated into your workflow.

Project Setup

1. Clone the Repository

To start working on the project, you need to clone the repository and change your working directory. Open your terminal and run:

git clone <repository-url>
cd <repository-name>

Then, immediately switch to the dev branch, where all development happens:

git switch dev

2. Create a Virtual Environment

Using uv, this step is as simple as:

uv venv
source .venv/bin/activate
uv sync --all-extras

The --all-extras flag ensures that all optional dependencies, including the extra [dev] dependencies, are installed. These include the pre-commit tool, as well as git-cliff for the changelog generation.

Tip

Whenever you need to execute something from within your virtual environment (e.g. dvc repro ... or lyprox runserver), you can prefix that command with uv run. For example: uv run dvc repro .... This will ensure that the command is executed within the context of your virtual environment and it will resync all dependencies before running the command, ensuring that you always have the latest versions of the packages installed.

3. Setup Pre-Commit Hooks

To ensure code quality and consistency, we use pre-commit hooks. These hooks will automatically run checks before you commit your changes.

The tool pre-commit should have already been installed as part of the uv sync --all-extras command.

To set up the pre-commit hooks, run:

pre-commit install

Tip

From time to time it might make sense to update the pre-commit hooks. You can do this by running:

pre-commit autoupdate

Then, don't forget to commit the changes that were made to the .pre-commit-config.yaml file.

Further Reading

• For source control best practices, check out the Source Control page in this wiki.
• For Python project setup, refer to the Python Project page.