# Contributing

Thanks for considering a contribution. This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md); by participating you agree to uphold it.


# Getting set up

- Python 3.13+ with [uv](https://docs.astral.sh/uv/).

- Clone with submodules -- the SDK is its own repository:

  ``` sh
  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/`:

  ``` sh
  UV_PROJECT_ENVIRONMENT=venv uv sync
  ```


# Before you open a PR

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

``` sh
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.

CI partitions the suite across two complementary jobs -- `gates` runs `pytest -q -n auto -m "not timing"` (parallel via pytest-xdist) and a dedicated `timing` lane runs the real-paced, marker-selected set serialized on its own VM. The unfiltered local command above executes the union of both, which is exactly what you want before a PR; a local full run can mirror the gates lane with `pytest -q -n auto -m "not timing"` (issue \#247). Reach for `-m 'not timing'` only when iterating on something unrelated and in a hurry.

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](https://github.com/madeinoz67/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](SECURITY.md) -- never an issue.