# Contributing

Source: https://athas.dev/docs/contributing

Set up Athas from source, run the required checks, and submit a focused contribution.

Athas uses Tauri, React, TypeScript and Rust. Start with a focused issue or reproducible bug and
check existing [issues](https://github.com/athasdev/athas/issues) before starting overlapping work.

## Requirements

- Git, Rust through [rustup](https://rustup.rs), Node.js 24.19.0 and Bun 1.3.14 for the current repository.
- macOS: Xcode Command Line Tools (`xcode-select --install`).
- Windows: Visual Studio Build Tools with Desktop development with C++ and WebView2.
- Linux: your distribution's native compiler, GTK, WebKitGTK 4.1 and Tauri dependencies.

The repository's `package.json`, setup scripts and `AGENTS.md` are authoritative if requirements
change between releases. Linux builds use the system WebKitGTK runtime; CEF setup is no longer required.

## Clone and run

```bash
git clone https://github.com/athasdev/athas.git
cd athas
bun setup
bun dev
```

`bun setup` installs dependencies and checks platform requirements. On supported Linux
distributions it offers the appropriate native dependencies. Read its output before installing
system packages. If your environment is already prepared, `bun install` installs JS dependencies.

## Find the right code

| Concern                              | Location                                  |
| ------------------------------------ | ----------------------------------------- |
| Frontend feature                     | `src/features/<feature>/`                 |
| Shared UI primitives                 | `src/ui/`                                 |
| Shared hooks and helpers             | `src/hooks/`, `src/utils/`                |
| Integration and theme implementation | `src/extensions/`                         |
| Rust feature logic                   | `crates/<feature>/`                       |
| Desktop wiring                       | `src-tauri/`                              |
| Public documentation                 | `athasdev/www`, under `src/content/docs/` |

Read `AGENTS.md` before making changes. Follow nearby patterns, reuse existing controls, and keep
a feature's components, services, stores and tests together.

## Validate a change

```bash
bun check
bun typecheck
bunx vp test run
```

Run the relevant tests while iterating. For Rust changes, also run `bun check:rust`; a focused
`cargo test -p <crate> <test-name>` can help during development. Verify visible changes in the app
with both themes and keyboard navigation where applicable.

## Build Linux packages

Run native package builds on Linux after installing its build dependencies:

```bash
bun build:linux:deb
bun build:linux:rpm
bun build:linux:appimage
```

The repository also provides `bun build:linux:tarball` for the portable tarball. See the current
package scripts for output locations and prerequisites.

## Submit a contribution

Keep each commit focused, explain the problem and resulting behavior, and include a concise test
plan. Add screenshots for visible changes.

Read the
[Contributor License and Feedback Agreement](https://github.com/athasdev/athas/blob/main/CONTRIBUTOR_LICENSE_AND_FEEDBACK_AGREEMENT.md)
and agree to it by checking the box in the pull request. Athas is licensed under
[AGPL-3.0](https://github.com/athasdev/athas/blob/main/LICENSE) and is also distributed under other
terms, such as through the Mac App Store or in commercial editions. The agreement gives Athas the
rights to include your contribution in both, and you keep the copyright in your work. Pull requests
without the agreement checked can't be merged.

For documentation changes in the website repository, follow its own `AGENTS.md` and use Vite+
with Node 24.19.0. Desktop and website validation commands are different.

## Documentation contributions

Report an inaccurate guide through its Suggest an edit link. Include the affected version and source behavior so the correction can be verified. [Documentation for LLMs](https://athas.dev/docs/for-llms) describes the generated Markdown exports.