# Contributing to agent-rooms-rs
Thanks for taking the time. This crate has a narrow job: stay byte-deterministic-compatible with the [Python parley reference](https://github.com/p-vbordei/agent-rooms) and pass the same conformance vectors. Most contributions fit into one of a few buckets — please read the relevant section before opening a PR.
## Ground rules
1. **This is the protocol-core Rust port.** Do **not** add an HTTP server, database layer, or MCP integration here. Those layers live in the Python packages (`parley-hub`, `parley-cli`, `parley-mcp`) and that is where they will stay. Suggested additions that don't fit the protocol-core scope will be closed with a pointer upstream.
2. **The Python source is the source of truth.** If you find a behavioural disagreement between this crate and the Python reference, the Python behaviour wins by default. Open an issue first so we can decide whether the bug is here or there.
3. **Wire-format changes must be proposed upstream first.** Any change that alters canonical bytes, signed-payload key sets, error semantics, freshness window, or turn-rotation order has to land in the Python reference (and its conformance vectors) before it lands here. All 25 vectors must stay green.
4. **Don't change conformance vectors locally.** Vectors in `vectors/` are mirrored verbatim from `conformance/vectors/` in the Python repo. Changing them masks real divergence.
5. **Keep the dependency surface minimal.** New runtime dependencies need a justification in the PR description — what does it buy that the current set (`ed25519-dalek`, `sha2`, `serde_json`, `chrono`, `thiserror`, `once_cell`, `hex`) can't?
## Dev setup
```bash
git clone https://github.com/p-vbordei/agent-rooms-rs
cd agent-rooms-rs
cargo build
cargo test
```
Rust ≥ 1.74. No native build steps beyond what `ed25519-dalek` and `sha2` already pull in.
## Running the tools
- `cargo test` — full suite (12 unit + 3 conformance + 1 doctest = 16 runs, covering 25 vectors).
- `cargo fmt` — format.
- `cargo clippy --all-targets -- -D warnings` — lint.
- `cargo run --example quickstart` — sanity-check the end-to-end roundtrip.
- `cargo run --features cli --bin parley -- keygen` — try the optional CLI.
## What goes in a PR
- A failing test (or a failing conformance vector replayed from the Python reference) before the fix.
- Symmetric updates to module-level docstrings if a public function changes shape.
- Append an entry to `CHANGELOG.md` under `[Unreleased]`.
- One logical change per PR. Refactors and behaviour fixes don't mix well in review.
## What does NOT go in a PR
- HTTP server code, database integration, or MCP server logic. See ground rule #1.
- Reformatting / reflow of files you didn't otherwise touch.
- New optional dependencies that "might be nice".
- Speculative API surface ("we might want X later").
## Reporting issues
Include:
- Rust version (`rustc --version`).
- Minimal canonical input or signed payload that reproduces.
- Whether you also see the issue in the Python reference — this drastically narrows the search.
## License
By contributing, you agree your contributions are licensed under AGPL-3.0-or-later (see [LICENSE](./LICENSE)).