Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (89 loc) · 4.49 KB

CONTRIBUTING.md

File metadata and controls

115 lines (89 loc) · 4.49 KB

Contributing

Keep oy small, boring, and useful.

Quick start

just check          # run all CI checks locally (fmt, clippy, test, rustdoc, smoke)
just fix            # auto-format and apply clippy suggestions, then check
just run -- chat    # run oy with arguments during development

If you don't have just, install it (cargo install just, brew install just, etc.) or run the individual commands listed below.

Local checks

Run these before opening a PR. just check runs them all.

cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked
cargo run --locked -- --help

Run clippy after formatting so its suggestions apply cleanly. Keep --all-targets --locked -- -D warnings intact: it checks tests/examples as well as the binary and treats every lint as something to fix before review.

For release-adjacent changes, also run:

just package          # or: cargo package --locked

Pre-commit hook (optional but recommended)

git config core.hooksPath .githooks

This runs cargo fmt --check and cargo clippy -- -D warnings before each commit so style/lint noise never reaches CI.

Development flow

  1. Inspect the relevant code and docs first.
  2. Make the smallest targeted change.
  3. Add or update focused tests for behavior changes.
  4. Run just check.
  5. Update README.md, SECURITY.md, docs, help text, and CHANGELOG.md for user-visible behavior changes.

Finding something to work on

  • Upstream Rig TODO — OpenAI-compatible reasoning/tool-call roundtrip: preserve empty reasoning_content, add an opt-in compatibility flag to emit reasoning_content: "" on assistant tool-call messages when a provider requires it, and cover the behavior with default-off and provider-compat tests. This should let Moonshot/Kimi-like models use thinking with tools without requiring oy to disable thinking by default.
  • docs/GOOD_FIRST_ISSUES.md — limited-scope tasks suitable for new contributors.
  • ISSUES.md — the latest audit findings; each finding lists the affected files and the trust boundary.
  • GitHub issues — look for good-first-issue and help-wanted labels.

Design rules

  • Prefer fewer concepts and explicit data flow.
  • Default to safe interactive behavior; make higher-risk modes explicit.
  • Inspect before edits; verify after edits.
  • Keep public docs aligned with implemented CLI help.
  • For security-sensitive work, name the trust boundary, validate near it, fail closed, and add focused tests.
  • For webfetch changes, keep model use simple: public docs should work by default with redirects and non-credentialed document-friendly headers, while every request/redirect remains public-only and sensitive headers stay denied.
  • Do not add providers, persistence, process, file, network, or credential handling without a concrete user need and focused tests.

Important paths

Path Role
src/agent.rs, src/agent/ Provider integration, model routing, sessions, transcripts, context compaction, tool loop
src/audit.rs Deterministic no-tools audit runner, file collection, chunking, prompts, report post-processing
src/cli.rs, src/cli/ Config paths, safety modes, terminal UI, chat shell, command handlers
src/tools.rs Tool schemas, tool dispatch, previews, todos, filesystem/network/mutation approval boundaries
src/lib.rs, src/main.rs Public facade and binary entry point
tests/ Integration and snapshot tests
.github/workflows/ci.yml CI checks (fmt, clippy, test, rustdoc, help smoke, doc drift, package)
.github/workflows/release.yml Release builds, artifact attestation, and crate publishing
justfile Local dev task runner; just check / just fix / just run

See also:

  • docs/architecture.md for runtime flow and module responsibilities.
  • docs/tool-safety.md for tool capability and boundary guidance.
  • SECURITY.md for user-facing security guidance.
  • ISSUES.md for the latest audit findings and remediation history.
  • docs/GOOD_FIRST_ISSUES.md for newcomer-friendly tasks.

Release notes

Update CHANGELOG.md for user-visible behavior changes. Keep fixed security findings in ISSUES.md with Status: Fixed until the next full audit refresh.