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¶
- Fork the repository and branch from
main. - Make one change: a fix with the test that shows it, or one feature. Keep unrelated clean-ups for another pull request.
- Run the gate for the part you changed, and regenerate anything generated that your change touches (build.md lists them).
- 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. Nofix:prefixes. - Open a pull request into
mainand fill in the template. CI runs what your change can have broken;ci-ok,dcoandlicenceshave 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.