# Contributing to agent-scroll-rs
Thanks for considering a contribution. The bar is high because **this repo implements a format**: any change to canonical encoding, hashing, or signing semantics breaks every existing scroll. Please read this file before opening a PR.
## Orientation
- **The TS reference is the source of truth.** This port must produce byte-identical canonical bytes and hashes. If you find a divergence, it's a bug here.
- **Conformance vectors are the contract.** The 20 byte-equality vectors in `fixtures/c1-hex.json` (and the 20 wire-format files in `vectors/`) come from the TS suite. Do not edit them. If a vector needs to change, change it upstream in [`agent-scroll`](https://github.com/p-vbordei/agent-scroll) first and copy it here.
- **Be careful with `canonical.rs`.** The `normalize_numbers` pass is a workaround for a `serde_jcs` precision gap (see [docs/architecture.md](docs/architecture.md)). Touching it without running `cargo test c1_byte_equality` is a way to break every consumer silently.
- **Idiomatic Rust is welcome.** The port should look like Rust, not transpiled TypeScript. `serde_json::Value`, `thiserror`, and `?` over manual error wrappers.
- **One logical change per PR.** Easier to review, easier to revert.
## Dev setup
```bash
git clone https://github.com/p-vbordei/agent-scroll-rs
cd agent-scroll-rs
cargo build
cargo test
```
## Run tests
```bash
cargo test # full suite (C1–C4)
cargo test c1_byte_equality # just the load-bearing test
cargo fmt --all -- --check # format check (CI gate)
cargo clippy --all-targets -- -D warnings # lint (CI gate)
cargo run --example quickstart # smoke the example
```
A healthy tree: `cargo test` green, `cargo clippy` clean, and `cargo run --example quickstart` prints `verify clean: ok=true` followed by `verify tampered: ok=false reason=BadHash`.
## Release process
1. Bump `version` in `Cargo.toml`.
2. Update `CHANGELOG.md` — move items from `[Unreleased]` to a new dated section.
3. Tag: `git tag v0.x.y && git push --tags`.
4. Publish: `cargo publish` (crates.io name: `agent-scroll`).
5. GitHub release notes mirror the CHANGELOG entry.
## Code style
- `cargo fmt` is authoritative.
- `cargo clippy -- -D warnings` is enforced in CI.
- No new runtime deps without strong justification. The current set (`serde_json`, `serde_jcs`, `sha2`, `ed25519-dalek`, `base64`, `thiserror`, `regex`, `once_cell`, `rand`) is deliberately small.