Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (84 loc) · 4.57 KB

CONTRIBUTING.md

File metadata and controls

132 lines (84 loc) · 4.57 KB
Raw

Contributing to Ravel

Contributions of code, documentation, tests, bug reports, benchmarks, and design feedback are welcome.

Ravel is a distributed observability database where object storage is the durable source of truth. Correctness, durability, and compatibility matter more than minimizing the size of an implementation.

Bug reports

Before you open an issue, search the existing issues. If the problem is already reported, add your details there instead of opening a duplicate.

Confirm that the bug reproduces against the current main branch HEAD. An older commit, a release tag, or a fork you have not updated is not enough. A report that reproduces only on an old commit may already be fixed, and a maintainer spends the same investigation time to find that out.

A useful bug report includes:

  • what you expected to happen
  • what happened
  • a minimal reproduction, confirmed against current main
  • the commit hash you reproduced it on
  • relevant logs, configuration, and environment details

Feature requests and larger changes

For substantial features, protocol changes, or architectural changes, open or join an issue before investing heavily in an implementation.

Explain the problem first. A good proposal describes the use case, the desired behavior, and the important trade-offs, and not only an implementation.

Some parts of Ravel are persistent contracts. Changes to segment formats, protobuf schemas, canonical identities, commit tokens, or object key layouts require an ADR and a version change. Do not modify persistent formats in place.

Making changes

Keep pull requests focused. Avoid unrelated refactoring, formatting, dependency changes, or cleanup.

When changing behavior:

  • add or update tests
  • update the relevant documentation in the same change
  • preserve Ravel's durability and consistency guarantees
  • avoid unsafe and unwrap/expect in production paths
  • keep exact semantics as the default unless approximation is explicitly exposed

Read the relevant specifications and ADRs in docs/ before changing storage, consistency, query, or protocol behavior.

For AI-assisted contributions, see AI_POLICY.md.

Building and testing

Ravel is a Rust workspace.

For fast iteration on a crate:

cargo check -p <crate>
cargo test -p <crate>

Before submitting a pull request, run the repository gates:

scripts/gates.sh

At minimum these enforce formatting, Clippy with warnings denied, and tests. The gate script also handles feature-specific checks such as SQL and Flight SQL where applicable.

Do not submit a PR that claims tests or benchmarks passed unless you ran them.

Commits

Ravel uses Conventional Commits with short, imperative subjects:

feat(query): add ...
fix(ingest): handle ...
docs: clarify ...
test(catalog): cover ...
chore: update ...

Keep the subject to 72 characters or fewer. Explain what changed and why in the commit body when it is not obvious.

Sign off commits:

git commit -s

Reference the relevant issue when applicable:

Refs: #123

or, when the change fully resolves it:

Fixes: #123

Pull requests

Before opening a PR:

  1. Rebase or update your branch against current main.
  2. Review your own diff.
  3. Remove unrelated changes and generated noise.
  4. Run scripts/gates.sh.
  5. Update documentation where behavior changed.

In the pull request, explain:

  • what changed
  • why it changed
  • how you verified it
  • any compatibility, performance, or operational implications

Small PRs with a clear purpose are easier to review than large mixed changes.

Review is part of the contribution process. Maintainers may ask for a different approach, additional tests, a smaller scope, or an ADR before a change can be merged.

Ravel also runs an agent review, and only when somebody asks for it:

  • Opening a pull request does not start a review, and neither does a label.
  • Somebody with write access to the repository starts one by commenting @claude-fleet review on the pull request. If you do not have write access, ask a maintainer to start it for you.
  • The review arrives as a single comment review of one commit, minutes later.
  • The review neither approves nor blocks. A person decides that. Treat its findings as one more opinion to answer, not as a gate.

See ADR-1586.

Licensing

Ravel is licensed under the Apache License 2.0.

Only contribute work that you have the right to submit under the project's license. The same requirement applies to code produced with AI tools or derived from other projects.