|
| 1 | +# Contributing to decibri-cli |
| 2 | + |
| 3 | +Thanks for your interest in contributing. This guide covers what you need to know. |
| 4 | + |
| 5 | +## Code of conduct |
| 6 | + |
| 7 | +Be respectful. Disagree with ideas, not people. No harassment. |
| 8 | + |
| 9 | +## How to report bugs |
| 10 | + |
| 11 | +1. Check the [issue tracker](https://github.com/decibri/decibri-cli/issues) for duplicates. |
| 12 | +2. If the bug is new, open an issue using the Bug Report template. |
| 13 | +3. Include: |
| 14 | + - OS and architecture |
| 15 | + - `decibri version` output |
| 16 | + - Steps to reproduce |
| 17 | + - Expected vs. actual behaviour |
| 18 | + - Command output (stderr and stdout) |
| 19 | + |
| 20 | +## How to request features |
| 21 | + |
| 22 | +Open an issue using the Feature Request template. Explain: |
| 23 | + |
| 24 | +- The problem you are trying to solve |
| 25 | +- Your proposed solution (if you have one) |
| 26 | +- Alternatives you considered |
| 27 | + |
| 28 | +Scope-note: v0.1.x is focused on the core command surface. Features flagged for v0.2.0 (VAD, raw PCM piping, diagnostics) or v0.3.0 (Homebrew/Scoop, config files) already have homes on the roadmap — we'd still appreciate an issue describing your use case, but code contributions for those features should wait until the relevant version milestone is open. |
| 29 | + |
| 30 | +## How to contribute code |
| 31 | + |
| 32 | +1. Fork the repository |
| 33 | +2. Create a feature branch: `git checkout -b feature/your-feature` |
| 34 | +3. Make your changes |
| 35 | +4. Ensure all CI checks pass locally: |
| 36 | + ``` |
| 37 | + cargo fmt --all -- --check |
| 38 | + cargo clippy --all-targets -- -D warnings |
| 39 | + cargo test |
| 40 | + cargo deny check # if you have cargo-deny installed |
| 41 | + cargo audit # if you have cargo-audit installed |
| 42 | + ``` |
| 43 | +5. For npm wrapper changes, also run: |
| 44 | + ``` |
| 45 | + cd npm/decibri-cli |
| 46 | + node --test tests/platform.test.js tests/sha256sums.test.js tests/version.test.js |
| 47 | + ``` |
| 48 | +6. Commit with a clear message |
| 49 | +7. Push and open a Pull Request |
| 50 | + |
| 51 | +### What we accept |
| 52 | + |
| 53 | +- Bug fixes with tests demonstrating the fix |
| 54 | +- Platform compatibility improvements |
| 55 | +- Documentation improvements |
| 56 | +- Performance improvements with a measurement |
| 57 | +- Small refactors that reduce code without changing behaviour |
| 58 | + |
| 59 | +### What we don't accept for v0.1.x |
| 60 | + |
| 61 | +- Features explicitly deferred to v0.2.0 (VAD, raw PCM piping, `decibri test`) |
| 62 | +- New audio format support beyond WAV (deferred to v0.2.0+) |
| 63 | +- Breaking changes to the CLI contract (subcommand names, flag names, exit codes, `version --json` schema) until v1.0.0 |
| 64 | +- Adding async runtimes (`tokio`, `async-std`) — the CLI is intentionally sync |
| 65 | +- Adding `env_logger` / `tracing` — stderr output is UI, not logs, in v0.1.x |
| 66 | + |
| 67 | +## Development setup |
| 68 | + |
| 69 | +### Requirements |
| 70 | + |
| 71 | +- Rust stable toolchain. MSRV is recorded in `Cargo.toml` under `rust-version`. |
| 72 | +- Node.js 18 or newer (for running the npm wrapper tests) |
| 73 | +- On Linux, `libasound2-dev` for the cpal backend: `sudo apt-get install libasound2-dev` |
| 74 | + |
| 75 | +### Building |
| 76 | + |
| 77 | +``` |
| 78 | +cargo build # debug build |
| 79 | +cargo build --release # optimised release build |
| 80 | +``` |
| 81 | + |
| 82 | +The release binary lands at `target/release/decibri` (or `decibri.exe` on Windows). |
| 83 | + |
| 84 | +### Running locally |
| 85 | + |
| 86 | +``` |
| 87 | +./target/debug/decibri version |
| 88 | +./target/debug/decibri devices |
| 89 | +./target/debug/decibri capture -o test.wav -d 3 |
| 90 | +./target/debug/decibri play test.wav |
| 91 | +``` |
| 92 | + |
| 93 | +### Testing |
| 94 | + |
| 95 | +``` |
| 96 | +cargo test # all Rust tests |
| 97 | +cd npm/decibri-cli && node --test tests/*.test.js # npm wrapper tests |
| 98 | +``` |
| 99 | + |
| 100 | +The Rust tests are hardware-independent and run in CI. Manual hardware tests (real microphone / speaker) are local-only because CI runners don't have audio devices. |
| 101 | + |
| 102 | +### Snapshot tests |
| 103 | + |
| 104 | +Some tests use [`insta`](https://insta.rs) for snapshot assertions. If you add a test or change snapshot-producing output, run: |
| 105 | + |
| 106 | +``` |
| 107 | +cargo insta review |
| 108 | +``` |
| 109 | + |
| 110 | +to approve changes after manual inspection. Do **not** blindly accept snapshots with `cargo insta accept` — review them first. |
| 111 | + |
| 112 | +## Project structure |
| 113 | + |
| 114 | +``` |
| 115 | +decibri-cli/ |
| 116 | +├── src/ Rust source |
| 117 | +│ ├── main.rs clap entry point + subcommand dispatch |
| 118 | +│ ├── exit.rs exit-code marker types |
| 119 | +│ ├── device_resolve.rs shared --device parsing + resolution |
| 120 | +│ └── commands/ |
| 121 | +│ ├── version.rs |
| 122 | +│ ├── devices.rs |
| 123 | +│ ├── capture.rs |
| 124 | +│ └── play.rs |
| 125 | +├── tests/ integration tests (hardware-independent) |
| 126 | +├── npm/decibri-cli/ npm wrapper package |
| 127 | +├── .github/ |
| 128 | +│ ├── workflows/ CI + release workflows |
| 129 | +│ ├── ISSUE_TEMPLATE/ |
| 130 | +│ └── dependabot.yml |
| 131 | +├── Cargo.toml |
| 132 | +├── deny.toml cargo-deny config |
| 133 | +├── CHANGELOG.md |
| 134 | +└── README.md |
| 135 | +``` |
| 136 | + |
| 137 | +## License |
| 138 | + |
| 139 | +By contributing, you agree that your contributions will be licensed under Apache-2.0. |
0 commit comments