Skip to content

Latest commit

 

History

History
253 lines (197 loc) · 9.73 KB

CONTRIBUTING.md

File metadata and controls

253 lines (197 loc) · 9.73 KB

Contributing to Grob

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.

Code of conduct

By participating in this project you agree to abide by the Contributor Covenant. Report unacceptable behaviour to conduct@a00.fr.

License and CLA

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.

Getting started

Prerequisites

  • Rust stable toolchain (edition 2021)
  • cargo-nextest for running the test suite
  • prek for the pre-commit hooks

Install prek with one of:

brew install j178/tap/prek
cargo install prek
curl -fsSL https://prek.sh | sh

First-time setup

git clone https://github.com/azerozero/grob
cd grob
prek install
cargo build
cargo nextest run

prek 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.

Branching model

Grob follows GitHub Flow.

feat/* or fix/* ──► main ──► release-plz PR ──► tag v* ──► release
  • main is 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 main named feat/<topic> or fix/<topic>. Open the PR against main.
  • 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 the v* tag when that PR merges.

Conventional Commits

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):).

Pull request process

  1. Open the PR against main with a clear title in Conventional Commit style (the squash-merge will use this title).
  2. Fill in the PR description. Describe the problem, the chosen approach, the blast radius, and any follow-up work.
  3. Enable auto-merge: gh pr merge <num> --auto --squash.
  4. Wait for the required CI checks to pass. Do not force-push after review has started unless you need to rebase onto main.
  5. Respond to review comments in the PR thread. One approval from a maintainer is enough for merge.
  6. The PR is squash-merged. The squash commit subject is the PR title, so keep it Conventional-Commits-compliant.

What CI checks

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_test

When 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.

Code style

  • Follow the Rust API Guidelines.
  • Doc comments on all public items. Grob enforces the doc-comment rules in CLAUDE.md — third-person present tense, no This function…, standard section order (# Errors, # Panics, # Safety, # Examples).
  • // comments explain why, not what. Tags are TODO:, 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 include dlp, oauth, tap, compliance, and harness.
  • No commented-out code. Delete it — git has the history.

Testing

  • Unit tests go in #[cfg(test)] mod tests inside the source file.
  • Integration tests live under tests/.
  • Snapshot tests use insta.
  • Cucumber scenarios live under tests/cucumber/features/ and must appear in tests/cucumber/RTM.md (requirements traceability matrix).
  • Benchmarks use criterion in benches/.

Common test commands:

cargo nextest run                     # all tests
cargo nextest run -E 'test(router)'   # filter by test name
cargo test --doc                      # doc tests only

Documentation

External 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.

Drift Surveillance

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.md to 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.

Reporting bugs

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.

Getting help

  • Questions about the architecture: read CLAUDE.md for a module-level map.
  • Questions about the roadmap: open a discussion in the GitHub Discussions tab.
  • Commercial support: mailto:hello@a00.fr.