# Contributing and governance This page is the published orientation for anyone who wants to work on Sotto, report a security issue, or understand what the license asks of them. It is a map, not the rulebook. The canonical governance files live at the repository root and are the source of truth; where this page and one of them disagree, the file wins and this page should be corrected. The three things you probably came here for: - [How to contribute](#how-to-contribute): set up the toolchain, run the gate, open a pull request. - [Reporting a security issue](#reporting-a-security-issue): do it privately, never in a public issue. - [The license: AGPL-3.0](#the-license-agpl-30): what copyleft and the network-use clause mean for you. If you are here to stand Sotto up rather than change it, start with the [architecture overview](architecture.md) for the contributor's map of the system and the [setup guide](setup.md) for the phase-by-phase build order. ## How to contribute The full workflow lives in [CONTRIBUTING.md](https://github.com/doyled-it/sotto/blob/main/CONTRIBUTING.md) at the repository root. The short version: - **Read the map first.** The [architecture overview](architecture.md) explains how the transport, orchestrator, models, and speech pipeline fit together, and points into the `specs/*.md` contracts that are the source of truth for every interface. When the overview and a spec disagree, the spec wins. - **Branch, never commit to `main`.** Work on a descriptive `feat/...` or `fix/...` branch and open a pull request. Direct commits to `main` are not allowed; integration happens through review. - **Run the gate for the component you touched.** These are the same commands CI runs. For the Python orchestrator, the required gate is `uv run ruff format --check . && uv run ruff check . && uv run pytest`, run with [uv](https://docs.astral.sh/uv/) from `server/orchestrator/`. `ruff` is the source of truth for both formatting and linting, and `pytest` needs no model, GPU, or network by default. The `app/` and `mac-app/` components have their own Gradle and Swift gates, listed in CONTRIBUTING.md. - **Write [Conventional Commits](https://www.conventionalcommits.org/).** For example `feat(orchestrator): stream chat completions over SSE`. Breaking changes use `!` after the type or a `BREAKING CHANGE:` footer. - **Test-first where the code is testable.** New behavior and bug fixes land with tests. The orchestrator suite uses in-process transports, so it stays fast and offline. - **Be kind.** Participation is governed by the [CODE_OF_CONDUCT.md](https://github.com/doyled-it/sotto/blob/main/CODE_OF_CONDUCT.md). ## Reporting a security issue Sotto's whole reason to exist is to keep your audio, text, and intent on hardware you control, so security and privacy reports are handled with care and in private. **Do not open a public GitHub issue for a vulnerability.** A public issue discloses the problem before there is a fix. Instead, report privately through GitHub's [Security Advisories](https://github.com/doyled-it/sotto/security/advisories/new) flow, which creates a report visible only to the maintainers. The full policy, including scope, response expectations, and safe-harbor terms, is in [SECURITY.md](https://github.com/doyled-it/sotto/blob/main/SECURITY.md). If you want to understand what Sotto defends and from whom before you dig in, the [threat model](specs/threat-model.md) is the authoritative statement of the trust boundaries and the default-deny posture. ## The license: AGPL-3.0 Sotto is licensed under the [GNU Affero General Public License v3.0](https://github.com/doyled-it/sotto/blob/main/LICENSE) (AGPL-3.0). By contributing, you agree your contributions are licensed under it. Every first-party source file carries an SPDX header so the license travels with the file. The AGPL is a strong copyleft license. That means anyone you give the software to, in modified or unmodified form, gets it under the same license, with the source and the freedom to run, study, and change it. The plain GPL requires you to share your source only when you distribute the software in binary form. The AGPL adds one clause on top, and it is the reason to choose the AGPL over the GPL for a networked service: - **The network-use clause (Section 13).** If you run a modified version of Sotto and let other people interact with it over a network, that counts. Section 13 obliges you to offer those users the corresponding source of your modified version. You cannot take the code, change it, put it behind a network service, and keep your changes private while others use it. For the person this project is built for, that clause changes nothing: - **Self-hosting for yourself imposes no obligation.** Running Sotto privately on your own Mac and phone, whether stock or with your own changes, is not distribution and is not offering it to other users over a network. You owe no one your source. Self-host freely, modify freely, keep it to yourself. The obligation only appears when you redistribute the software or operate a modified version as a network service for other people. That is the deal the AGPL makes, and it is deliberate: it keeps a privacy tool from being quietly turned into a closed hosted product.