Skip to content

Contributing to comind

Thanks for your interest in comind. Bug reports, language and framework support, documentation fixes and code are all welcome.

Before you start

  • For anything beyond a small fix, open an issue first so we can agree on the approach.
  • Security issues go through SECURITY.md, not public issues.
  • By contributing, you agree that your contributions are licensed under the MIT License.

Development setup

You need Rust 1.94.1 or newer (the minimum supported version, checked in CI), plus protoc and cmake:

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

git clone https://github.com/sayef/comind && cd comind
cargo test
cargo run -q -- eval graph -v                        # resolver quality on the fixture org

Tests that need a bucket or an LLM key are opt-in; everything else runs offline.

Checklist for a pull request

  • cargo fmt --all and cargo clippy --all-targets -- -D warnings are clean.
  • cargo deny check passes (licences, advisories and sources; install with cargo install cargo-deny --locked).
  • New behaviour has tests. Resolver, contract and infrastructure changes add cases to tests/fixtures/org with gold edges in expected.toml, and comind eval graph stays at 100% precision and recall.
  • Real-world changes are checked on real repositories as well: no new spurious contracts, and a note in the pull request of what changed.
  • Performance changes include criterion results (cargo bench --bench graph); CI also posts a base-against-head comparison to the job summary of each pull request.
  • Determinism holds: the same repositories give the same graph, ids and ordering.
  • Changes to stored formats (Lance tables, ledger records, facts) keep reading what older versions wrote (#[serde(default)] on new fields).
  • Commands, MCP tools and configuration keys are reflected in the README, docs and the changelog (under ## [Unreleased]).

Project layout

One crate: a library with one module per pipeline stage, and the comind binary (see ARCHITECTURE.md). Language support lives in src/lang/ behind the LangSpec trait; contract linking in src/resolve/contracts.rs.

Style

  • Follow the surrounding code. Keep comments short: say what the code does, and put the reasoning in the pull request.
  • Prefer returning errors to panicking on bad input, especially on anything read from storage or repositories.
  • Precision over recall: an unresolved edge is better than a wrong one, and nothing reaches an agent's context unless it is grounded and trusted.
  • Measure before optimising, and include the numbers in the pull request.

Releasing

Every push to main opens or updates a release pull request (version bump and changelog entry). Merging it publishes nothing. To release, run the Release-plz workflow by hand (Actions → Release-plz → Run workflow, or gh workflow run release-plz.yml): it publishes the crate, tags v<version>, creates the GitHub release, and the Release workflow attaches the binaries.

Commit messages

One short line in the imperative mood ("Add Express route detection"). The pull request description says why.