# Contributing

Thanks for wanting to help. Issues, PRs, and ideas are all welcome.

## Quick start

```bash
pnpm install
pnpm tauri dev
```

Prereqs: Rust (stable), Node 20+, pnpm, plus your platform's [Tauri prerequisites](https://tauri.app/start/prerequisites/).

## Before opening a PR

Run these and make sure they pass:

```bash
pnpm exec tsc --noEmit          # frontend types
cd src-tauri && cargo clippy    # Rust lint
cd src-tauri && cargo fmt       # Rust format
```

Build a release bundle at least once if you touched anything in `src-tauri/`:

```bash
pnpm tauri build
```

## Branches

Branch off `main`. Use these prefixes (kebab-case):

| Prefix     | Use for                                  |
| ---------- | ---------------------------------------- |
| `feat/`    | New feature                              |
| `fix/`     | Bug fix                                  |
| `chore/`   | Refactor, tooling, config, dependencies  |
| `docs/`    | Docs-only changes                        |
| `perf/`    | Performance work                         |

Examples: `feat/split-panes`, `fix/explorer-focus`, `chore/windows-bundle-config`.

Don't open PRs from your fork's `main` branch — it makes future syncs painful for you. Always work on a feature branch.

## Issues first for non-trivial work

For anything beyond a typo, a small bug fix, or a clear `good-first-issue` — **open an issue first** and wait for a maintainer to ack the approach. A 10-minute conversation saves a 500-line PR that doesn't fit the roadmap.

If an issue already exists for what you want to do, comment "I'll take this" before starting so we don't duplicate work.

## What we want

- **Bug fixes** — always.
- **Features** — open an issue first if it's non-trivial. We'd rather discuss the approach than reject a finished PR.
- **Docs / typos / small UX fixes** — just send the PR.
- **New AI providers** — see `src/modules/ai/providers/`. Keep BYOK; no hardcoded keys.
- **Themes / icon packs** — yes, but keep the bundle size in check.

## What we don't want

- Telemetry, analytics, or anything that phones home.
- Hardcoded API keys or accounts. Terax stays BYOK.
- Large dependencies for small wins. The bundle is ~7 MB and we want it to stay light.
- Sweeping refactors with no functional change.

## Code style

- Follow the existing patterns. Read adjacent files before adding new ones.
- TypeScript: no `any` unless you really mean it.
- Rust: `cargo fmt` + `clippy` clean.
- Few comments. Code should explain itself; comments are for the *why*, not the *what*.
- No emoji in code or commit messages.

## Commits & PRs

We squash-merge every PR — the **PR title becomes the squash commit**, so it should follow [Conventional Commits](https://www.conventionalcommits.org/):

```
feat(terminal): add split panes
fix(explorer): prevent input from disappearing on create
chore(deps): bump tauri to 2.x
docs(readme): clarify Linux install on Arch
```

Types: `feat`, `fix`, `chore`, `docs`, `perf`, `refactor`, `test`, `build`, `ci`.
Common scopes: `terminal`, `editor`, `explorer`, `pty`, `ai`, `settings`, `tabs`, `shortcuts`, `agents`, `ui`.

Within a PR, individual commit messages can be whatever — they get squashed.

**One logical change per PR.** A PR that adds a feature, fixes an unrelated bug, and reformats `.gitignore` is three PRs. Split them.

**Open a draft PR early** if you want feedback mid-flight; mark "Ready for review" when done. Fill out the PR template — what changed, why, how you tested. Include screenshots / GIFs for any UI change.

### What gets merged faster

- Clear problem statement
- Small, focused diff
- Follows existing patterns (read 2-3 nearby files before writing yours)
- `pnpm exec tsc --noEmit` clean
- Manual testing notes ("I tested by doing X, Y, Z")

### What gets bounced back

- Mixed-concern PRs ("split this please")
- Large architectural PRs without prior discussion
- New dependencies without justification
- Breaking changes without migration notes
- Incidental reformatting unrelated to the change (adds noise to review)
- AI-generated code that obviously wasn't read by the author

## Project layout

```
src-tauri/        Rust backend — PTY, FS, shell, plugins
src/
  modules/
    terminal/     xterm.js sessions + OSC handlers
    editor/       CodeMirror stack
    explorer/     File tree
    tabs/         Tab model
    ai/           Agents, sessions, tools, mini-window
    header/       Top bar + search
    statusbar/    Bottom bar
    shortcuts/    Keymap
  components/     shadcn/ui + AI Elements
```

## Security issues

Don't file them as issues — see [SECURITY.md](SECURITY.md).

## License

By contributing you agree your work is licensed under [Apache-2.0](LICENSE).