CONTRIBUTING.md

# Contributing

Thanks for wanting to contribute! This repository uses a strict CI and formatting policy to keep code consistent.

## Recommended local setup

We recommend using `pyenv` + `venv` to create a reproducible development environment. A helper script `dev-setup.sh` is included to automate the steps:

```bash
# Run the helper script (default Python version can be overridden)
./dev-setup.sh 3.11.4
source venv/bin/activate

# Install pre-commit hooks
pip install -r dev-requirements.txt
pre-commit install
```

## Before opening a PR

- Run formatting and linting: `make format` and `make ci-check`
- Run tests: `pytest`
- Ensure pre-commit hooks pass: `pre-commit run --all-files`

## CI expectations

- CI runs pre-commit checks and the full test suite on PRs
- The project enforces Python >=3.10 in CI

Please open issues or PRs against `main` and follow the branch naming conventions described in the README.