Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
59 lines (37 loc) · 1.7 KB

CONTRIBUTING.md

File metadata and controls

59 lines (37 loc) · 1.7 KB
Raw

Contributing to cusp

Thanks for your interest in cusp! This guide should be enough to get you from a fresh clone to a green test run.

Before your first patch, skim ARCHITECTURE.md for a module map and overview of how capture, gating, and the AirPlay session fit together.

Dev setup

cusp depends on PortAudio at the system level. Install it first:

# Raspberry Pi / Debian / Ubuntu
sudo apt install libportaudio2 python-dev-is-python3

# macOS
brew install portaudio

Then install the project and its dev dependencies with uv:

uv sync

uv sync installs the dev dependency group (ruff, pytest, pytest-asyncio) alongside runtime deps.

Running tests

uv run pytest -v

Tests live under tests/. pytest-asyncio is configured in asyncio_mode = "auto", so async tests do not need @pytest.mark.asyncio decorators.

Linting and formatting

cusp uses ruff for both linting and formatting. CI runs the same two checks you should run locally:

uv run ruff check .
uv run ruff format --check .

To auto-apply formatting:

uv run ruff format .

Ruff configuration (target version, line length, selected lint rules) lives in pyproject.toml under [tool.ruff].

Pull requests

Before pushing a branch, please:

  • Run uv run ruff check . and uv run ruff format --check . — CI will fail otherwise.
  • Run uv run pytest -v and make sure everything passes.

CI runs the test suite on Python 3.10 through 3.14 and the ruff checks on 3.14. Keep changes compatible with the minimum supported version (currently 3.10, declared in pyproject.toml).