English · Português
Thanks for your interest! This guide covers reporting a problem, setting up the environment, testing and sending your change.
- Search the issues first: it may already exist.
- Open one with the right template: bug or idea. Blank issues are disabled so every report comes with the information we need.
- For bugs, include the term7 version (right corner of the status bar), your distro and desktop and, for the
integrations, your
ghandclaudeversions. A screenshot or GIF helps a lot. - Security issues do not go in issues: see SECURITY.md.
English or Portuguese are both fine.
term7 is used daily on Linux (Pop!_OS 24.04, COSMIC) + GitHub (gh) + Claude Code, and that is the setup
that matters most not to break. Changes to the GitHub and Claude integrations (gh.rs, claude.rs,
suggest.rs, agents.rs, usage.rs, src/lib/github.ts) need tests and a description of how you tested them
in the app.
You need Node 24+ and one of these to build the Rust side:
- Docker (recommended, installs nothing on your machine):
docker compose run --rm build - Native: Rust via rustup + the Tauri libraries:
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \ libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
npm install
npm run tauri dev # native: opens the app with hot reloadnpm test: frontend tests (Vitest).npm run build: type-check and frontend build.docker compose run --rm --no-deps dev bash -c "cd src-tauri && cargo check && cargo test": Rust, no warnings.docker compose run --rm build: builds the.debintodist-deb/.scripts/install-local.sh: installs it for your user (no sudo) with a launcher icon. Test the installed app (~/.local/bin/term7).
Running the UI inside Docker works (
docker compose run --rm dev), but without a GPU it is slow. To judge performance and interaction, use the installed app.
New tests: new logic or a new parser comes with tests. In Rust, in the file's own mod tests, with
real-shaped (anonymized) data. In the frontend, in a *.test.ts next to the module.
We use Conventional Commits. The version is computed from them:
| Prefix | Version bump |
|---|---|
fix: |
patch (1.0.1) |
feat: |
minor (1.1.0) |
feat!: or BREAKING CHANGE: |
major (2.0.0) |
docs:, chore:, refactor:, style:, test:, ci: |
no release |
Example: feat: open diff file in the viewer
- Branch off
dev(feat/...,fix/...). - Make sure the tests,
npm run buildandcargo checkpass with no warnings. - Open the PR against
devand fill in the template: what changed, how to test, and screenshots for visual changes. CI runs the tests and builds the.debon the PR as a check; nothing is published.
dev: integration. Feature and fix PRs land here. Merging intodevdoes not release.main: only takes thedev → mainPR. Each merge releases everything accumulated ondev: semantic-release computes the version, CI builds the.deb, attaches it to the release and keeps only the 3 latest.devis never deleted. When mergingdev → main, don't click "Delete branch".
The version only comes from the release: the workflow writes it into package.json before building. In the
repo package.json stays at 0.0.0-dev, so a local build shows up as dev.
- UI text, code comments and internal docs are in Brazilian Portuguese; identifiers in English. If you don't write Portuguese, write in English and a maintainer will help.
- Short comments that explain why.
- See CLAUDE.md for the project structure and technical conventions.
By contributing, you agree that your contribution is distributed under the project's MIT license.