Contributing

The canonical version of this guide lives in CONTRIBUTING.md at the repository root.

Development setup

This project uses uv for dependency management.

git clone git@github.com:Riverfount/flask-confluent-kafka.git
cd flask-confluent-kafka
uv sync

Linting

uv run ruff check .

Type checking

uv run mypy

src/flask_confluent_kafka is checked under mypy's strict mode (see [tool.mypy] in pyproject.toml) — the package ships a py.typed marker, so keeping it clean matters for downstream users too.

Documentation site

Docs are built with MkDocs and the Material theme, from the docs/ folder.

uv sync --group docs
uv run mkdocs serve

Then open http://127.0.0.1:8000.

Running tests

uv run pytest -v

CI runs the full coverage-gated suite on every pull request against main:

uv run pytest --cov=flask_confluent_kafka --cov-report=term-missing --cov-fail-under=90

main is protected — ruff check, mypy, and the coverage-gated test suite must all pass before a pull request can be merged, including for repo admins.

Making changes

1. Check the issue tracker for existing issues related to what you want to work on, or open a new one for anything not tracked yet.
2. Create a branch off main.
3. Make your changes, keeping them focused on the issue at hand.
4. Make sure ruff check ., uv run mypy, and uv run pytest pass.
5. Open a pull request referencing the issue it closes (e.g. Closes #1).