Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
97 lines (73 loc) · 4.3 KB

CONTRIBUTING.md

File metadata and controls

97 lines (73 loc) · 4.3 KB
Raw

Contributing

Thanks for your interest in OmniGraph. This page is the practical how-to; the rules and decision authority behind it live in GOVERNANCE.md.

Start in the right place

I want to… Go to Notes
Report a bug or wrong behavior Open an Issue — bug form Concrete and reproducible. A maintainer triages it; once labelled accepted it's open for a PR.
Propose a feature / share an idea Open an Issue — feature form A maintainer triages it. accepted means a PR may follow; a larger design gets needs-rfc and goes through an RFC first.
Propose a design / RFC An Issue first, then an RFC pull request Get the issue accepted before investing in the RFC. Merge may publish a draft for review; only status: accepted authorizes implementation — see docs/rfcs/README.md.
Fix something / implement a change A pull request Must link an accepted issue or accepted RFC — unless it's trivial (below).
Report a security vulnerability SECURITY.md Do not open a public Issue.

GitHub Discussions are not used — Issues are the only inbound channel.

When can I just open a PR?

The trivial fast-lane — open directly, no prior issue/RFC needed, when the change is clearly broken-fixing with small blast radius and no design impact: typo and wording fixes, doc corrections, dependency bumps, comment fixes, obvious one-line CI tweaks. If you cannot tell trivial from real, it is real — open the issue. Anything more substantial needs a backing accepted issue or accepted RFC first, so the why is agreed before the how is reviewed. A PR that turns out to be non-trivial will be redirected — that's about process, not the merit of the change.

Development

Building requires the Rust stable toolchain and protoc (the Protocol Buffers compiler — a build dependency of the storage substrate):

brew install protobuf                                  # macOS
sudo apt-get install -y protobuf-compiler libprotobuf-dev   # Debian/Ubuntu

The first clean build compiles the Arrow/Lance storage stack and can take many minutes depending on hardware and network cache state. For the shortest edit loop, check or test only the package you changed before running the workspace gate:

cargo check -p omnigraph-engine --locked
cargo test -p omnigraph-engine --test traversal

Substitute the owning package and existing test target; the coverage map in docs/dev/testing.md identifies them. Before merging a non-trivial change, run the canonical feature-superset gate:

cargo test --workspace --locked \
  --features omnigraph-engine/failpoints,omnigraph-cluster/failpoints

If you touch S3-backed flows, the CI model uses a local RustFS instance for integration tests.

OpenAPI spec

openapi.json is a committed artifact generated from the Utoipa annotations in crates/omnigraph-server. CI never regenerates or commits it — it only checks for drift and fails the build if the committed copy disagrees with the source. When your change touches the server API surface, regenerate locally and commit the result in the same PR:

OMNIGRAPH_UPDATE_OPENAPI=1 cargo test -p omnigraph-server --test openapi openapi_spec_is_up_to_date

Cargo features

omnigraph-server has an optional aws feature that pulls in the AWS Secrets Manager SDK for a bearer-token backend. Default builds omit it — most contributors never compile the AWS code path.

When you touch crates/omnigraph-server/src/auth.rs or any AWS-conditional code, verify both configurations:

cargo test -p omnigraph-server                  # default
cargo test -p omnigraph-server --features aws   # AWS enabled

CI runs both.

Pull Requests

  • Link the backing accepted issue or accepted RFC (Closes #123, or reference the RFC) — or mark the PR as trivial per the fast-lane.
  • Keep changes focused; one logical change per PR.
  • Include tests for behavior changes when practical.
  • Update public docs when the user-facing surface changes.

New to the codebase? Read AGENTS.md — the architecture map and the always-on invariants every change is reviewed against.