# Contributing

> The product contract is [docs/specs/v10/](docs/specs/v10/README.md).

## Prerequisites

- Rust toolchain pinned by `rust-toolchain.toml`, installed automatically by
  rustup. Bump it deliberately: every bump changes the shipped helper's
  digest (see the file's header comment).
- Git.
- Omarchy Quattro and Quickshell development files for QML validation.
- Qt Quick Test tools (`qmltestrunner`, `qmllint`).
- ShellCheck for the retained Bash helper.

Rust/Cargo is the application toolchain. Do not add Node, npm, Bun, pnpm, Yarn,
Deno, or JavaScript build tooling.

## Safe development

Do not install a work-in-progress build into the live desktop. Use:

- isolated Git worktrees;
- temporary plugin roots reached through an isolated `HOME`;
- isolated `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, and `XDG_STATE_HOME`;
- fake provider executables and fixture data;
- offscreen QML tests.

The live `$HOME/.config/omarchy/plugins` and `shell.json` are reserved for the
explicit final QA gate.

## Standard verification

```bash
cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
git diff --check
```

QML/plugin verification:

```bash
# PATH qmllint is a stub reporting version 1.0 that stays SILENT even on an
# undefined type — the Qt6 binary path is mandatory here too
/usr/lib/qt6/bin/qmllint -I /usr/share/omarchy/shell \
  ./*.qml components/*.qml
omarchy plugin validate .
# PATH qmltestrunner is Qt5 and fails SILENTLY (errors only in journald) —
# the Qt6 binary path and both env vars below are mandatory
QT_QPA_PLATFORM=offscreen QML_XHR_ALLOW_FILE_READ=1 QT_LOGGING_TO_CONSOLE=1 \
  /usr/lib/qt6/bin/qmltestrunner \
  -input tests/qml \
  -import /usr/share/omarchy/shell \
  -import . \
  -o -,txt
```

Shell helper:

```bash
shellcheck scripts/agent-bar-open-terminal
```

## Test rules

- Write the failing test before behavior.
- Never use live provider credentials or provider network in tests.
- Inject clock, filesystem, process runner, HTTP, and XDG roots.
- Test single-provider and all-provider paths through the same policy.
- Treat QML behavior, accessibility, scrolling, and screenshots as release
  gates.
- Do not update snapshots merely to silence an unexpected change.

## Provider changes

Read [docs/dev/new-provider.md](docs/dev/new-provider.md). Provider-specific behavior
stays behind the adapter. QML receives schema-v2 normalized data only.

## Commits

- Use English Conventional Commit subjects of at most 50 characters.
- Keep one reviewable behavior per commit.
- Do not bypass hooks or signatures.
- Record exact commands, results, screenshots, and deviations in the PR.

## Documentation

Active documentation is English and must match executable contracts.
Every versioned changelog release section, `docs/releases/**`,
and ADR bodies 0001–0003 remain
historical: they record how things were and are never rewritten. The
`[Unreleased]` changelog section, the ADR index, ADR 0004 and later, the
numbered files under `docs/specs/v10/`, and `docs/guide/**` are active and
must match the shipped behavior. `docs/specs/v10/amendments/**` are the approved design
documents as written on their approval date: frozen, never rewritten, and
superseded wherever a numbered spec file or the code says otherwise.

## Release

Merging to `master` triggers an automatic release: a patch bump (or a minor
or major version set by hand in the pull request, see
`docs/dev/releasing.md`), Rust gates, and a single `release: v{version}` commit that stamps
`bin/agent-bar`, `bundle.json`, and the manifest version straight into the
repository root — the root IS the plugin tree, per
[ADR 0006](docs/adr/0006-single-repository-distribution.md) — followed by
the tag and GitHub Release on that same commit. There is no separate
distribution repository and no release assets to attach; the commit itself
is the release. Implementation may prepare a release candidate and open a
ready PR, but merge itself is the release decision and requires separate
explicit authorization. See [docs/dev/releasing.md](docs/dev/releasing.md).