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).
• Node.js 20+ (optional, only for building the documentation site under docs/; not needed for the Rust workspace).

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 docmd site under docs/ — the primary user-facing documentation surface, published at https://timescale.github.io/rsigma/. The whole docmd project (config, package.json, local plugin, assets, and Markdown under docs/content/) lives in docs/. A PR that adds or changes:
   • A user-facing capability → add or update the relevant docs/content/guide/<topic>.md page and an entry in docs/docmd.config.js navigation (under the appropriate User Guide sub-category)
   • A CLI subcommand or flag → update the matching docs/content/cli/<group>/<command>.md page (e.g. docs/content/cli/engine/daemon.md)
   • A daemon config key → update docs/content/cli/engine/daemon.md and any cross-referenced guide page
   • A public library API surface → update the matching docs/content/library/<crate>.md page
   • A Prometheus metric, HTTP endpoint, environment variable, lint rule, feature flag, or backend → update the corresponding docs/content/reference/<topic>.md page

From docs/, run npm install once, then npm run docs:build and npm run docs:validate before pushing docs changes; .github/workflows/docs.yml enforces both 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 CONTRIBUTING.md.