Skip to content

Contributing

The repo is laid out as a standalone project (pyproject.toml, .venv, custom_components/, tests/); deploy by copying custom_components/climate_orchestrator/ into your HA config (see the installation guide).

Dev environment setup

Uses uv, ruff, mypy, and pytest with pytest-homeassistant-custom-component.

uv venv --python 3.14 && uv sync --dev   # create env, install deps
uv run ruff check . && uv run ruff format --check .
uv run mypy custom_components/climate_orchestrator
uv run pytest                            # fast: tests only
uv run pytest --cov=custom_components/climate_orchestrator   # with coverage (CI gate: 95%)
uv run mutmut run                        # mutation-test the control/ math

See Testing for the test layout, the coverage gate, and how to run and triage mutation tests, and Tooling for what CI enforces.

Local docs preview

The documentation site is MkDocs Material; preview it locally without adding docs dependencies to the project environment:

uv run --group docs mkdocs serve

Project conventions

  • Every change ships code + tests + docs. Contributions are expected to keep docs and tests in step with behaviour: user-facing changes update the user documentation (especially the controls & settings reference and how it controls), design changes update the relevant developer chapter, and every change ships with tests (pure unit tests for logic, pytest-homeassistant-custom-component for HA-facing glue) with ruff and pytest green.
  • strings.json is byte-identical to translations/en.json. hassfest validates strings.json; the two files are sync-checked in CI and pre-commit, so edit them together (or copy one over the other) — a drifted pair fails the gate.
  • Conventional commit types cut releases. fix: → patch, feat: → minor, feat!:/BREAKING CHANGE: → major; pushing a green feat/* or fix/* branch cuts an rcN prerelease and merging to main cuts the stable release — so write commit messages as if they ship, because they do. See Releases.
  • Maintain quality_scale.yaml. custom_components/climate_orchestrator/quality_scale.yaml tracks the HA integration quality scale honestly (45 done / 7 exempt; no remaining todos). A change that affects a tracked rule (new entity behaviour, diagnostics, config flow, etc.) updates the corresponding entry — including its comment rationale — in the same PR.

Coding style

The full set of code conventions (typing, frozen dataclasses, enums over magic strings, pure functions, async correctness) lives in Tooling and is enforced by ruff + mypy in CI.

Next: head back to the architecture overview, or the user guide introduction.