Contributing¶

Thanks for contributing to aioafero.

Getting started¶

Fork and clone the repository.
Install Python 3.12+ (3.12, 3.13, and 3.14 are tested in CI).
Sync dev dependencies:
```
uv sync --extra test
```
Run lint and tests before opening a PR — see Testing and CI.

Pull request checklist¶

uv run tox -e lint
uv run tox run-parallel -p auto -o --skip-env lint

Report bugs and feature requests on GitHub Issues.

Code layout¶

src/aioafero/ — library source
src/aioafero/v1/ — v1 API bridge, auth, controllers, models
tests/ — pytest suite (mirrors src/ layout)

Device and protocol logic belongs in aioafero, not downstream Home Assistant integrations. Add new API behavior here first, then wrap it in Hubspace-Homeassistant.

Documentation¶

User guide and API docs live in docs/. Build locally:

uv sync --extra docs
uv run tox -e docs

Hosted docs are published on Read the Docs. The Publish workflow triggers an RTD build after CI passes (same gate as PyPI); pushes and PRs only run tox -e docs as a build check.

One-time RTD setup:

Import the GitHub repo on readthedocs.org with project slug aioafero (matches .readthedocs.yaml and the Publish workflow).
Click This file exists when prompted for .readthedocs.yaml.
Create an API token at readthedocs.org/account/tokens/ and add it as READTHEDOCS_TOKEN in the GitHub repo secrets.
Disable automatic builds on push so only Publish deploys docs: in GitHub Settings → Webhooks, edit the Read the Docs hook and uncheck Push (leave the integration connected so RTD can pull source when the API build runs).