Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (61 loc) · 2.85 KB

CONTRIBUTING.md

File metadata and controls

80 lines (61 loc) · 2.85 KB
Raw

Contributing to zorp

Thanks for taking a look at zorp. It's early and moving fast, so please read this before sending a PR.

Before you start

For anything beyond a small fix (typos, docs, obvious bugs), open an issue first to discuss the change. This avoids wasted work on PRs that don't fit the project's direction.

Read AGENTS.md for the tool-agnostic project instructions, docs/superpowers/specs/ for the approved designs, and docs/decisions/ for the product and architecture decision log. Check there before proposing something that's already been decided against.

Development setup

Requires protoc (the Protocol Buffers compiler), needed to build the lance-encoding dependency. Install it with your package manager, e.g. brew install protobuf (macOS) or apt-get install protobuf-compiler (Debian/Ubuntu).

git clone https://github.com/aviskaar/zorp.git
cd zorp
cargo build --workspace --exclude zorp-track

zorp-track bundles DuckDB and pulls in LanceDB/Arrow/DataFusion, which take 20-30 minutes to compile cold. The command above skips it; drop --exclude zorp-track only when you're touching zorp-track or the research feature, and budget time for that first build.

Testing

cargo test --workspace

The research feature (validate, investigate, co-write, deliver capabilities) isn't exercised by the default test run. If you touch zorp-agent research-feature code, also run:

cargo test -p zorp-agent --features research

Both must pass before a PR is reviewed. Note that CI only runs cargo test --workspace --exclude zorp-track (see docs/DECISIONS.md, 2026-08-13): zorp-track and the research feature depend on duckdb (bundled) and lancedb, which are too slow to cold-compile on every CI run. Running both commands above locally before opening a PR is on you.

Style

  • Prose in docs, commit messages, and comments should read plainly: no em dashes or en dashes as punctuation, short direct sentences.
  • Follow existing code patterns in the crate you're touching. src/, zorp-agent/, zorp-mcp/, zorp-eval/ are inherited harness code; zorp-track/ and the four research capabilities are zorp-specific. Keep new zorp-specific work clearly separated from inherited harness code.
  • No unnecessary abstractions, comments that restate the code, or speculative features. Keep changes scoped to what the issue asks for.

Pull requests

  • Keep PRs focused on one change.
  • Include or update tests for behavior changes.
  • Update relevant docs (README.md, docs/decisions/, the design spec the change belongs to) when a change affects them.
  • CI (build + test) must pass.

Reporting issues

Open a GitHub issue with steps to reproduce, expected vs. actual behavior, and your environment (OS, Rust version).