# Contributing to Speedwave

Speedwave's core is open. If you want to fix a bug, add a platform, or improve the docs, start with [development setup](/docs/contributing/development-setup/) to get Rust, Node.js, and the platform tools running, then check [testing](/docs/contributing/testing/) before you open a pull request.

The Makefile is the entry point for everything: `make setup-dev` installs dependencies, `make dev` starts the desktop app in hot-reload mode, and `make check-all` runs the full quality gate (`check`, meaning lint, clippy, type-check, and format, plus tests, coverage, and a dependency audit). Do not call cargo or npm directly. The Makefile keeps working directories and flags consistent across the Rust crates, the Angular frontend, and the MCP servers.

## Engineering principles

A short version of the rules that shape the codebase:

- **KISS.** Speedwave is a thin orchestration layer over Lima, nerdctl, and containerd, not a reimplementation of them. Call the right existing tool rather than building a custom one.
- **YAGNI.** Build what the implementation plan asks for. `speedwave logs`, `status`, and `stop` are not CLI subcommands because the Desktop GUI already covers them.
- **DRY.** Duplicated logic moves to `speedwave-runtime` (or `mcp-servers/shared/` for MCP code). Catalogues with a single source of truth, like Anthropic model strings, get edited at that source, not at each call site.
- **SOLID.** Each runtime type has one job (`ContainerRuntime` only manages containers), platforms add new implementations without touching callers (`LimaRuntime`, `WslRuntime`), and callers depend on the `LockedRuntime` interface rather than a specific platform.
- **Rule of three.** Don't extract an abstraction until a pattern shows up a third time.

Logging follows its own rules: all Rust code goes through the `log` crate facade, never `eprintln!`/`println!` for diagnostics, and every log sink runs through the secret sanitizer in `log_sanitizer.rs` before anything reaches a file, stderr, or the desktop webview.

The git workflow has a hard line too: never bypass a git hook, never merge with `--admin` or a weakened branch protection rule, and never mark a failing check as expected. Every commit ships its tests alongside the code, covering happy paths, edge cases, error paths, and state transitions where they apply. Skipped tests are not allowed; a failing test gets fixed or removed. Follow the Boy Scout Rule: fix small bugs, typos, and dead code you encounter along the way, and report anything too large for the current change instead of leaving a `TODO` comment.

[Development setup](/docs/contributing/development-setup/)
  [Testing](/docs/contributing/testing/)