Contributing

Thanks for considering a contribution. This project follows the Contributor Covenant; by participating you agree to uphold it.

Getting set up

  • Python 3.13+ with uv.

  • Clone with submodules — the SDK is its own repository:

    git clone --recurse-submodules https://github.com/madeinoz67/benchweave.git

  • This repo keeps a non-dot venv/; keep uv pointed at it so it does not create a stray .venv/:

    UV_PROJECT_ENVIRONMENT=venv uv sync

Before you open a PR

All gates must pass locally — the same commands CI runs:

uv run pytest -q
uv run ruff check .
uv run mypy          # config-driven; also covers packages/sdk/src
make check-sdk-standards

A handful of registry tests sign fixtures with private keys that are not in the repository (CI materialises them from secrets); on a fresh clone those tests skip with a named reason — skips there are expected, failures are not.

Bug fixes ship test-first: a failing test that reproduces the bug lands in the same change as the fix.

Workflow

  • Work on a feature branch; main only receives merges via pull request.
  • Conventional commits (feat:, fix:, docs:, chore:, …) — the changelog is generated from them by git-cliff.
  • packages/sdk is a separate repository (benchweave-sdk). Changes under it are committed and pushed there first, then the advanced submodule pointer lands as a second commit here.
  • Keep commits small — one logical change each.

Reporting bugs

Open an issue with the version, your Python version, and a minimal reproduction. Security issues follow SECURITY.md — never an issue.