Thanks for your interest in contributing. Grob is a multi-provider LLM routing proxy written in Rust. This document describes the workflow, conventions, and checks you need to pass before a pull request can be merged.
For the in-depth technical guide see
docs/how-to/contribute.md. This file is the
top-level summary and the authoritative reference for branching, commit
style, and the review process.
By participating in this project you agree to abide by the
Contributor Covenant.
Report unacceptable behaviour to conduct@a00.fr.
Grob Core is licensed under Apache-2.0. By submitting a pull request you agree to the Contributor License Agreement, which grants A00 SASU the right to distribute your contributions under Apache-2.0 and, when needed, under commercial or proprietary licenses for paid products.
- Rust stable toolchain (edition 2021)
cargo-nextestfor running the test suiteprekfor the pre-commit hooks
Install prek with one of:
brew install j178/tap/prek
cargo install prek
curl -fsSL https://prek.sh | shgit clone https://github.com/azerozero/grob
cd grob
prek install
cargo build
cargo nextest runprek install wires the pre-commit hooks that run cargo fmt, clippy,
and gitleaks on every commit, with documentation and dependency checks on
push. The test suite runs separately and in CI. The configuration lives in prek.toml.
Grob follows GitHub Flow.
feat/* or fix/* ──► main ──► release-plz PR ──► tag v* ──► release
mainis the only long-lived branch. Never commit or push directly to it — it is protected by a GitHub ruleset that requires a reviewed PR.- Create feature branches from
mainnamedfeat/<topic>orfix/<topic>. Open the PR againstmain. - When two PRs modify overlapping files, base the second branch on the
first (
git checkout -b feat/B feat/A) so the second PR does not need a merge when the first lands. - Enable auto-merge on every PR as soon as CI starts:
gh pr merge <num> --auto --squash. Do not wait for CI to merge by hand. - Releases are handled by release-plz. It watches
main, opens a Release PR with a version bump and changelog entries, and creates thev*tag when that PR merges.
Every commit message must follow Conventional Commits v1.0.0:
<type>(<scope>): <short description>
[optional body]
[optional footer]
Allowed types and what they trigger:
| Type | release-plz bump | When to use |
|---|---|---|
feat |
minor | New user-visible capability |
fix |
patch | Bug fix |
refactor |
patch | Internal restructuring, no user impact |
perf |
patch | Performance improvement |
docs |
none | Documentation only |
test |
none | Test-only changes |
chore |
none | Build, tooling, dependency bumps |
style |
none | Formatting |
Only feat, fix, refactor, and perf trigger a version bump.
Breaking changes get a ! after the type or a BREAKING CHANGE:
footer and are bumped to the next major version.
Scopes are optional but encouraged when the change is localised (for
example feat(routing): or fix(openai-compat):).
- Open the PR against
mainwith a clear title in Conventional Commit style (the squash-merge will use this title). - Fill in the PR description. Describe the problem, the chosen approach, the blast radius, and any follow-up work.
- Enable auto-merge:
gh pr merge <num> --auto --squash. - Wait for the required CI checks to pass. Do not force-push after
review has started unless you need to rebase onto
main. - Respond to review comments in the PR thread. One approval from a maintainer is enough for merge.
- The PR is squash-merged. The squash commit subject is the PR title, so keep it Conventional-Commits-compliant.
The required Documentation examples job checks documentation and source changes.
It loads the TOML files in docs/examples/, verifies selected Markdown examples
against the configuration schema and their expected settings, and syntax-checks
the Python, Node.js and shell snippets in the SDK/setup/provider guides.
It does not call providers or execute installation and deployment commands.
Run the same checks locally with Python 3.8+, Node.js, Bash and cargo-nextest installed:
python3 scripts/ci/doc-examples.py
cargo nextest run --locked --test lib --no-tests=fail doc_examples_test
cargo nextest run --locked --test lib --no-tests=fail example_configs_testWhen changing a checked heading, example or intended setting, update its contract
in tests/integration/doc_examples_test.rs in the same PR. The existing Docs Lint
workflow checks Markdown style and links separately. A missing test suite, failed
example, or cancellation of the selected job blocks the required gate.
Pull requests select jobs from .github/workflows/ci.yml according to changed
files. See the CI flow for triggers and required gates:
| Stage | What it checks |
|---|---|
| Quality gates | fmt, clippy, doc, actionlint |
| Tests | Unit + integration on Ubuntu, macOS, Windows |
| Feature powerset | cargo-hack compiles every feature combination |
| Audit | cargo-audit + cargo-deny for advisories and licences |
Mutation testing samples changed critical Rust files on eligible PRs; broader
mutation jobs and cross-target builds run on main. Documentation outside src/
skips unrelated runtime jobs; Markdown changes under src/ trigger Rust checks.
- Follow the Rust API Guidelines.
- Doc comments on all public items. Grob enforces the doc-comment rules
in
CLAUDE.md— third-person present tense, noThis function…, standard section order (# Errors,# Panics,# Safety,# Examples). //comments explain why, not what. Tags areTODO:,FIXME:,HACK:,NOTE:,SAFETY:(capitalised, colon, sentence ending with a period).- File size target: 200–500 lines. If a module exceeds 500 lines, check whether it has a single responsibility.
- Feature flags use
#[cfg(feature = "…")]. Optional features includedlp,oauth,tap,compliance, andharness. - No commented-out code. Delete it — git has the history.
- Unit tests go in
#[cfg(test)] mod testsinside the source file. - Integration tests live under
tests/. - Snapshot tests use
insta. - Cucumber scenarios live under
tests/cucumber/features/and must appear intests/cucumber/RTM.md(requirements traceability matrix). - Benchmarks use
criterioninbenches/.
Common test commands:
cargo nextest run # all tests
cargo nextest run -E 'test(router)' # filter by test name
cargo test --doc # doc tests onlyExternal documentation follows the Diátaxis framework. Each file belongs to exactly one category:
| Folder | Type | Question answered |
|---|---|---|
docs/tutorials/ |
Tutorial | How do I learn this? |
docs/how-to/ |
How-to | How do I solve X? |
docs/reference/ |
Reference | What are the exact details? |
docs/explanation/ |
Explanation | Why does it work this way? |
docs/decisions/ |
ADR (MADR 4.0) | Why was this decision made? |
When the scope of a change involves a new architectural decision, add
an ADR in docs/decisions/NNNN-short-title.md using
docs/decisions/0000-template.md.
CONTRACTS.md records the intended behavior of
critical functions and APIs — invariants, pre/postconditions, boundary
behavior, and known drifts. It is the reference against which an
autophagy scan compares the code to catch silent semantic drift:
changes that compile and pass tests but quietly violate the original
intention.
When your change alters the behavior of a contracted item, you must keep
CONTRACTS.md in lockstep:
- Intentional behavior change — update the relevant contract section (invariants, postconditions, boundary behavior) so it describes the new intended behavior, and add a dated entry under Known drifts explaining what changed and why. The drift entry is the audit trail; do not silently overwrite an invariant.
- Bug fix — do not edit
CONTRACTS.mdto match a bug. The contract is the source of truth; fix the code so it matches the contract instead. - New contracted surface — if you add a function or API critical enough to be audited (routing, dispatch, spend, DLP, storage), add a new contract section following the existing format.
Reviewers should reject a PR that changes contracted behavior without a
corresponding CONTRACTS.md update. If you are unsure whether an item is
contracted, search CONTRACTS.md for its name before merging.
File bugs at https://github.com/azerozero/grob/issues/new. Include
the grob version (grob --version), the invocation, and a reproduction
— ideally the shortest TOML config and the curl or SDK call that
triggers the problem. Redact API keys and OAuth tokens before pasting.
For security-sensitive issues follow SECURITY.md —
do not open a public issue.
- Questions about the architecture: read
CLAUDE.mdfor a module-level map. - Questions about the roadmap: open a discussion in the GitHub Discussions tab.
- Commercial support: mailto:hello@a00.fr.