Contributing¶

Setup¶

uv sync            # install deps (add --extra libvirt on a Linux host)
make test          # fast suite
make lint          # ruff + type checkers

Rules¶

• Package manager: uv (never pip).
• Type hints: required on all public functions/classes; checked by ty, pyrefly, and mypy.
• Line length: 88 characters (Ruff default).
• Docstrings: for public APIs; intent matters.
• Design: functional core / imperative shell (see Architecture). Side effects at the edges, pure logic inside; prefer dataclasses/attrs over raw dicts.
• Commits: conventional commits, one line of summary, no mention of AI tools.

Pre-commit checklist¶

make format        # ruff format + ruff check --fix
make lint          # all type checkers pass
uv run pytest      # all tests pass
git status         # no untracked junk

Where things live¶

• New endpoint → a focused module in src/cloudalone/controllers/ (one controller each); shared helpers/DTOs in controllers/_common.py.
• New wire field → schemas.py (the external contract; keep it faithful to hcloud).
• New server type / image → catalog.py.
• Deploy changes → deploy/deploy.py; validate with ./deploy/test-in-docker.sh before a real box.

Docs¶

These docs are built with Zensical from docs/src/:

cd docs
make serve         # live preview
make build         # static build into docs/public/