iotta / CONTRIBUTING.md
📖 CONTRIBUTING.md

Contributing to iotta

Thanks for working on iotta. This guide covers the conventions a change must follow — whether you're a human contributor or an automated agent.

Development setup

cd server
pip install uv
uv pip install -e ".[dev,audio]"        # add ,observability for OTLP export
PYTHONPATH=src python -m pytest tests/ -v

See README.md for running the server and client, and DEPLOY.md for deployment.

Branch & commits

The trunk is main. Keep commits focused and write clear, imperative messages (e.g. fix(backup): ...). CI (.github/workflows/test.yml) runs the test suite on every push and pull request — keep it green.

Tests

Default to TDD for behavior changes (red → green → refactor). The suite must pass with no network access and no system audio libraries (opuslib is mocked):

cd server && PYTHONPATH=src python -m pytest tests/ -v

Changelog — required for visible changes

iotta maintains a changelog at CHANGELOG.md, following Keep a Changelog and Semantic Versioning.

In the same commit/PR as your change, add an entry under the ## [Unreleased] section, in the appropriate group:

Group Use for
Added New features
Changed Changes to existing behavior
Deprecated Soon-to-be-removed features
Removed Removed features
Fixed Bug fixes
Security Vulnerability fixes

Add an entry for anything user- or operator-visible: features, behavior changes, fixes, and changes to configuration, CLI commands, the HTTP/admin API, or the device protocol. You may skip the changelog only for internal-refactor-only or docs-only changes.

Releasing

  1. Move the ## [Unreleased] entries under a new ## [x.y.z] - YYYY-MM-DD heading.
  2. Set the matching version in both server/pyproject.toml and client/pyproject.toml.
  3. Update the compare/release links at the bottom of CHANGELOG.md.
  4. Tag the release: git tag vX.Y.Z.

Until 1.0, the minor version tracks development phases (see docs/roadmap.md).

Automated agents

Claude Code and Copilot follow the same rules. Their briefs (CLAUDE.md and AGENTS.md) point back here for the changelog policy, so there is one source of truth for humans and agents alike.