# Contributing to Vaken
Vaken is a small, focused macOS menu-bar utility. Contributions that
keep the scope tight and the binary tiny are most welcome.
## Before opening a PR
1. **Open an issue first** for anything non-trivial — features, UI
changes, new menu items, behaviour shifts. Bug-fix PRs without an
issue are fine if the bug is obvious from the diff.
2. **Build locally** — `./scripts/verify.sh` runs the same `cargo fmt
--check` / `cargo clippy -D warnings` / `cargo build --release` that
CI does. Add `--bundle` to also produce the `.app`.
3. **Add a CHANGELOG entry** under `[Unreleased]`. Breaking changes go
under `### Changed (breaking)`.
## Scope
Vaken is deliberately minimal:
- Wraps `caffeinate -dimsu -w <pid>` to keep the Mac awake on demand.
- Lives in the menu bar (`LSUIElement = true`); no Dock icon, no
Cmd-Tab presence.
- No telemetry, no network calls, no auto-update, no settings panel.
- Native Rust binary (~few MB), no Electron, no webview, no JS.
Changes that grow any of these surfaces — settings UI, preferences
file, background networking — should be discussed in an issue first.
The bar for adding state or dependencies is high.
## Code style
- `cargo fmt --all` — no exceptions. CI fails on drift.
- `cargo clippy --all-targets -- -D warnings` — fix lints rather than
suppressing them.
- Comments explain *why*, not *what*. Identifier names cover the *what*.
- macOS-only: `src/main.rs` carries a top-of-file `compile_error!` gate
for non-macOS targets. Preserve it.
## Releases
Releases are tag-driven:
```bash
# Bump version in Cargo.toml + CHANGELOG.md, commit, then:
git tag -a v0.X.Y -m "v0.X.Y"
git push origin v0.X.Y
```
The `release.yml` workflow builds the universal `.app`, attaches it to
the GitHub Release, and publishes the crate to crates.io. See
[`.github/workflows/release.yml`](.github/workflows/release.yml).
## Reporting bugs
Use the GitHub issue templates:
- **Bug report** — include macOS version, chip (Intel/Apple Silicon),
Vaken version (`vaken --version` or About menu), and reproduction
steps. Attach `Console.app` output filtered for `vaken` if relevant.
- **Feature request** — describe the workflow you're trying to enable
and why the existing toggle doesn't cover it.
## License
By contributing, you agree your changes are dual-licensed under MIT and
Apache-2.0 (the project's licenses; no CLA required).