Contributing¶

We welcome pull requests, issues, and feature suggestions from the community. Please take a moment to review this guide and our Code of Conduct before contributing.

Setting Up the Project¶

Prerequisites: Docker must be installed on your machine.

make build-with-dev-dependencies   # build the dev container (includes dev dependencies)

That’s it. All development happens inside the container — no need to manage Python versions or Poetry locally.

Useful commands:

Command

Description

make build-with-dev-dependencies

Build the dev Docker image

make test

Run the full test suite

make lint

Check for lint errors (ruff)

make fix

Auto-fix lint and formatting issues

make shell

Drop into the container for debugging

Branching & PR Policy¶

We use version branches for releases. Each published release has its own branch, and all new PRs must target the next upcoming version branch — never main.

Example:

  • Current released version is 0.4.0

  • Your PR’s base branch should be 0.4.1

Can’t find the upcoming branch? Open an issue asking us to create it.

Semantic Versioning¶

We follow Semantic Versioning:

Type

Example

When to use

PATCH

0.4.1

Bug fixes, docs, performance improvements

MINOR

0.5.0

New features, backwards-compatible changes

MAJOR

1.0.0

Breaking changes

PR Checklist¶

Before submitting your PR, make sure you’ve done the following:

Branch

  • PR is targeting the correct upcoming version branch (e.g. 0.4.1), not main

Code

  • Ran make lint with no errors

  • Ran make test and all tests pass

  • Added or updated tests for any new or changed behavior

Docs

  • Updated README if user-facing behavior changed

  • Updated this documentation if applicable

Changelog

  • Added a short entry under the upcoming version in CHANGELOG.md

General

  • PR description explains what changed and why

  • Linked the related issue using Closes #123 (if one exists)

Release Flow (Maintainers Only)¶

Note

This section is for maintainers only. External contributors do not need to worry about this.

  1. Merge approved PRs into the upcoming version branch (e.g. 0.4.1)

  2. Run the full test suite one final time: make test

  3. Tag and publish the release from that branch

  4. Create the next upcoming version branch (e.g. 0.4.2) immediately after

Questions?¶

Open an issue or start a Discussion on GitHub.