Skip to content

Contributing to Troupe

Troupe is Apache-2.0 (LICENSE), and a contribution is accepted under the same licence. Bug reports, fixes, documentation and clients written against PROTOCOL.md are all welcome. Everyone here follows the code of conduct. A security problem goes to SECURITY.md, never to a public issue.

Before you start

For anything larger than a small fix, open an issue first, or say on an existing one that you are taking it, so nobody builds the same thing twice, or something the design rules out. Issues labelled good first issue are small and self-contained. ARCHITECTURE.md is the design and the decisions say why things are the way they are: a change that undoes a numbered decision says so. In the code, a comment says why in its own words and cites no decision by number (conventions).

Build and check

The toolchain is pinned in .tool-versions: Erlang/OTP, Elixir, Zig and Node. mise install (or asdf install) installs it; on Windows, scripts/setup-windows-toolchain.ps1. Then, per part of the repository:

mix deps.get && mix check                                        # the umbrella
(cd clients/tui && mix deps.get && mix check)                    # the TUI
(cd clients/gui && pnpm install && pnpm build && pnpm test)      # the GUI

mix check is the gate; scripts/ci runs CI's own job on your machine, and some suites need the services from scripts/dev-up. docs/developer/ has the rest: local setup, testing, conventions.

A first contribution

  1. Fork the repository and branch from main.
  2. Make one change: a fix with the test that shows it, or one feature. Keep unrelated clean-ups for another pull request.
  3. Run the gate for the part you changed, and regenerate anything generated that your change touches (build.md lists them).
  4. Commit with git commit -s (see below), the message in the house style: the behaviour that is now true, in plain prose, and a body saying what was wrong and why this is the fix. No fix: prefixes.
  5. Open a pull request into main and fill in the template. CI runs what your change can have broken; ci-ok, dco and licences have to pass. A maintainer reviews it and merges it.

The maintainers batch their own fixes on development-<date> branches (fixing-issues.md); a pull request from outside goes straight to main.

Sign-off (DCO)

Every commit carries a Signed-off-by: line with your name and email. It certifies the Developer Certificate of Origin: that you wrote the change, or have the right to submit it under the project's licence. git commit -s adds it. For a branch that lacks it, git rebase --signoff main and push the branch again. The dco check requires it of commits authored from 2026-09-27, when the rule started; the history before that is unsigned. Dependabot's own commits are not checked, since a bot can't certify anything; whoever merges its pull request answers for the version it moves, and a commit added to its branch needs that person's sign-off.

Coding agents

AGENTS.md holds the rules for agents working here, and they hold for what an agent writes for you: no Co-Authored-By: trailers or "Generated with" lines, PowerShell scripts in plain ASCII. The sign-off is yours whoever typed the change, and so is the responsibility for it.

Dependencies

A new dependency has to be under a licence the policy at the top of scripts/licences.exs allows: permissive ones pass, copyleft ones need a reviewed exception, which the script's header explains. The licences check says which. After adding or removing a package, fetch everything (mix deps.get at the root and in clients/tui, pnpm install in clients/gui, and Rust installed for cargo), run elixir scripts/licences.exs and commit docs/third-party-licences.md and THIRD-PARTY-NOTICES.txt with it. A package whose licence texts change needs the same: the notices carry them into every download and image.