Contributing

Contributing

See also CONTRIBUTING.md. main is protected: open a PR (status checks must pass), sign off commits (DCO), and use Conventional Commit messages.

Dev setup (Python)

python -m venv .venv && . .venv/Scripts/activate   # or bin/activate
pip install -e . --group dev

Checks (all must pass before a PR):

ruff check .
ruff format --check .
mypy
pytest --cov=argus --cov-report=term-missing --cov-fail-under=90

pytest skips the integration-marked ClickHouse test unless clickhouse-connect is installed and CLICKHOUSE_DSN is set.

Dev setup (frontend)

cd frontend
npm ci
npm run dev        # Vite dev server, proxies /api + /metrics to :9191
npm run lint       # eslint
npm test           # vitest
npm run build      # type-check + build to dist/

Conventions

• Match surrounding style; ruff (line length 100) + mypy --strict are authoritative.
• Keep the seven invariants intact. The most common trap: never add guild_id/user_id/channel_id as a Prometheus label (route per-guild data to the history sink instead).
• Add or update tests for any behaviour change; keep core coverage high.
• Hooks must stay O(1) and fail-open.

Commit + DCO

git commit -s -m "feat(adapters): add X"

The -s adds the Signed-off-by trailer certifying the Developer Certificate of Origin. PRs whose commits are not signed off will be asked to amend.

Architecture map

core (neutral model + hooks) -> adapters (prometheus, otlp) + exposition (aiohttp) + dashboard (SPA) + history (analytics). core imports no adapter. Start at Architecture and Invariants.