Contributing to rsigma🔗

Thank you for considering a contribution to rsigma! This document covers the basics of setting up a development environment, running tests, and submitting changes.

Getting Started🔗

Prerequisites🔗

• Rust toolchain (MSRV: 1.88.0). Install via rustup.
• Docker (optional, required for integration tests that use testcontainers).

Building🔗

cargo build --workspace

Running Tests🔗

# Unit and integration tests
cargo test --workspace

# Clippy lints (must pass with zero warnings)
cargo clippy --workspace --all-targets --all-features -- -D warnings

# Formatting check
cargo fmt --all -- --check

# Dependency audit
cargo deny check

Development Workflow🔗

Branching🔗

• Feature branches: feat/<name>
• Fix branches: fix/<name>
• Target main for all PRs.

Commit Messages🔗

Use Conventional Commits style:

• feat(parser): add support for temporal_ordered correlation
• fix(convert): prevent SQL injection in identifier interpolation
• test: add snapshot tests for parser AST
• ci: add cargo-deny job to audit workflow

Pull Requests🔗

• Keep PRs focused on a single concern.
• Reference any related issue numbers.
• Ensure CI is green before requesting review.
• New public API surface should include rustdoc with examples.
• New features should include tests. Prefer integration tests for cross-crate behavior and unit tests for isolated logic.

Code Quality🔗

• cargo fmt and cargo clippy must pass with zero warnings.
• cargo deny check must pass (licenses, advisories, bans, sources).
• Do not add unsafe code without justification and a safety comment.
• Avoid .unwrap() in library crates. Use ? or return descriptive errors. .unwrap() is acceptable in tests.

Testing🔗

• Unit tests live in #[cfg(test)] modules alongside the code they test.
• Integration tests go under crates/<crate>/tests/.
• Snapshot tests use insta. Run cargo insta review after updating snapshots.
• Fuzz targets live in fuzz/fuzz_targets/. Add a fuzz target for any new untrusted input surface.
• Benchmarks use Criterion and live in benches/.

Documentation🔗

Two surfaces must stay in sync with what each release ships:

1. Crate READMEs (README.md at the workspace root, plus crates/<crate>/README.md) — for any public API or behavior change. The root README documents runtime/security features (Docker hardening, signature verification, supported features).
2. The mkdocs site under docs/ — the primary user-facing documentation surface, published at https://timescale.github.io/rsigma/. A PR that adds or changes:
3. A user-facing capability → add or update the relevant docs/guide/<topic>.md page and the section's .pages nav file (the awesome-pages plugin reads .pages to control nav order)
4. A CLI subcommand or flag → update the matching docs/cli/<group>/<command>.md page (e.g. docs/cli/engine/daemon.md)
5. A daemon config key → update docs/cli/engine/daemon.md and any cross-referenced guide page
6. A public library API surface → update the matching docs/library/<crate>.md page
7. A Prometheus metric, HTTP endpoint, environment variable, lint rule, feature flag, or backend → update the corresponding docs/reference/<topic>.md page

Run mkdocs build --strict locally before pushing docs changes; .github/workflows/docs.yml enforces it on every PR.

A CHANGELOG.md entry under ## [X.Y.Z] - YYYY-MM-DD is part of the release commit (the same content gets copied to the GitHub Release body). For features with public-API impact, the release notes mention the affected README and docs/ pages so reviewers can sanity-check the doc sync.

Architecture🔗

rsigma is a Cargo workspace with the following crates:

License🔗

By contributing, you agree that your contributions will be licensed under the MIT License.

For the project's development workflow conventions (branching, testing, releases, supply-chain hygiene), see the development-workflow rules.