# Contributing to RustStream
RustStream is the core crate in this repository plus thirteen broker crates, each in a repository
of its own. This page covers the environment, the checks a change passes before review, and how a
core change is tested on the broker crates.
## Repositories
The broker crates depend on the core through crates.io, and each repository builds on its own.
To work across them, clone them side by side in one directory:
```text
RustStream/
ruststream/
ruststream-amqp/
ruststream-fred/
ruststream-gcp-pubsub/
ruststream-kinesis/
ruststream-lapin/
ruststream-nats/
ruststream-pulsar/
ruststream-rdkafka/
ruststream-rumqttc/
ruststream-sea-file/
ruststream-sqlx/
ruststream-sqs-sns/
ruststream-zeromq/
```
```bash
mkdir RustStream && cd RustStream
for repo in ruststream ruststream-amqp ruststream-fred ruststream-gcp-pubsub ruststream-kinesis \
ruststream-lapin ruststream-nats ruststream-pulsar ruststream-rdkafka ruststream-rumqttc \
ruststream-sea-file ruststream-sqlx ruststream-sqs-sns ruststream-zeromq; do
git clone "https://github.com/powersemmi/$repo.git"
done
```
## Environment
- **Rust** through rustup. `rust-toolchain.toml` selects stable with rustfmt and clippy. The
minimum supported version is 1.95: `rustup toolchain install 1.95` builds against it with
`cargo +1.95 check --workspace --all-features`. The MSRV rises only to a Rust release at least
six months old, and only in a minor release.
- **just**, which runs every recipe below.
- Per task:
| `just deny` | cargo-deny | `cargo install cargo-deny --locked` |
| `just cov` | cargo-llvm-cov | `cargo install cargo-llvm-cov --locked` |
| `just bench` | valgrind | the system package manager; the recipe installs the benchmark runner itself, at the release `Cargo.lock` pins |
| `just brokers` | jq | the system package manager |
| the documentation site | Node.js 22 | `npm ci` in `website/`, then `npm start` (one language) or `npm run build` (all three, strict) |
| a broker's live suite | Docker with Compose | the Docker documentation |
## Checking a change to the core
```bash
just check # rustfmt, clippy, cargo check on the feature edges, rustdoc, compile-fail snapshots
just test # the test suite, the reduced-feature legs, doctests on both feature edges
just ci # both
```
The compile-fail snapshots record the exact wording of the stable rustc that
`rust-toolchain.toml` selects, so `just check` runs them on stable.
`just cov` holds line coverage at 95%, the same floor CI holds. `just bench --baseline=main`
compares instructions and allocations per message against `main`, and a pull request that changes
the cost cites its numbers.
## Testing a change on the broker crates
`just brokers` runs every broker crate's test suite against the core in this working tree:
```bash
just brokers # every broker cloned next to the core
just brokers nats fred # the named ones
```
The brokers are found next to the core's main checkout, so the recipe also runs from a git
worktree elsewhere. Each broker runs `cargo test --workspace --all-features`, the same command as
its own `just test`, against this working tree. For the run, its lock file takes `ruststream` from
this tree instead of the release it pins, and the lock file is restored afterwards. A broker whose
`ruststream` requirement does not accept this tree's version fails rather than test a release. The
broker builds from its own working tree, on the branch it has checked out and with its uncommitted
edits.
The summary lists the brokers that passed, the ones that failed, and the repositories skipped for
having no crate or no `ruststream` dependency. The recipe fails when any broker failed, when a
named one cannot be tested, and when it finds no broker.
A change to the surface the brokers use goes like this:
1. Make the change in the core on a branch.
2. Adapt the affected brokers, each on a branch in its own repository.
3. Run `just brokers <name>...` from the core until every one passes.
4. Open the core pull request, then one pull request per broker. A broker's pull request raises
its `ruststream` requirement to the core release that carries the change.
These suites run on each broker's in-process transport. A change to the broker contract is also
checked against a real broker. In the broker's repository, `just test-brokers` starts its
Compose stand and runs the live suite against the core from crates.io. Against the local core,
the live suite runs like this:
```bash
just brokers-up
saved="$(mktemp)" && cp Cargo.lock "$saved"
cargo update -p ruststream --config "patch.crates-io.ruststream.path='../ruststream'"
# the live suite
cp "$saved" Cargo.lock && rm "$saved"
just brokers-down
```
The live suite is the command `test-brokers` runs, with the same `--config` added to
`cargo test`. The patch alone does not replace the release the lock file pins, so `cargo update`
points the lock file at the local core first. Copying the saved file back restores the lock file
as it was, uncommitted edits included. A broker without a lock file gets one from
`cargo update`: delete it instead of copying back.
## Pull requests
- One logical change per pull request.
- Open it as a draft. CI runs when it is marked ready for review.
- A pull request merges as one squashed commit, after the `CI result` check and one approving
review. Commits are signed.
- Documentation changes with the code. An item's rustdoc says what it is and does. A module
overview says how a topic is done. The site holds the entry pages in English, Russian and
Chinese, and an edit reaches all three.
- The agent skills in `.agents/skills/` change with the behaviour they teach. Their eval suite in
`.agents/evals/` runs with `claude plugin eval . --allow-tools Write Edit`, which compares each
case with and without the plugin.