Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
175 lines (120 loc) · 10 KB

CONTRIBUTING.md

File metadata and controls

175 lines (120 loc) · 10 KB

Contributing to Rig

Thank you for considering contributing to Rig! Here are some guidelines to help you get started.

General guidelines and requested contributions can be found in the How to Contribute section of the documentation.

Issues

Before reporting an issue, please check existing or similar issues that are currently tracked.

Additionally, please ensure that if you are submitting a bug ticket (ie, something doesn't work) that the bug is reproducible. If we cannot reproduce the bug, your ticket is likely to be marked either wontfix or closed (although it's likely we'll take note of it in case there's a secondary occurrence).

Pull Requests

Contributions are always encouraged and welcome. Before creating a pull request, create a new issue that tracks that pull request describing the problem in more detail. Pull request descriptions should include information about it's implementation, especially if it makes changes to existing abstractions.

PRs should be small and focused and should avoid interacting with multiple facets of the library. This may result in a larger PR being split into two or more smaller PRs. Commit messages should follow the Conventional Commit format (prefixing with feat, fix, etc.) as this integrates into our auto-releases via a release-plz Github action.

Unless the PR is for something minor (ie a typo), please ensure that an issue has been opened for the feature or work you would like to contribute beforehand. By opening an issue, a discussion can be held beforehand on scoping the work effectively and ensuring that the work is in line with the vision for Rig. Without any linked issues, your PR may be liable to be closed if we (the maintainers) do not feel that your PR is within scope for the library.

It is also highly suggested to comment on issues you're interested in working on. By doing so, it allows others to see that something is being worked on and therefore avoids frustrating situations, such as multiple contributors opening a PR for the same issue. In such a case, any duplicate PRs will be closed unless it is clear that the original contributor is unable to continue the work.

You can link your PR back to a given issue by writing the following in your PR message:

Fixes #999

This will then auto-link issue 999 (for example) and will automatically close the issue once the PR has been merged.

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

Code Contribution Guidelines

Most non-trivial open source projects often have a set of code contribution guidelines that are highly advised to stick to for the easiest path to a merge. Such policies also exist to ensure that the project is able to remain easy to contribute to.

While we will not strictly enforce any guidelines as such because we want to make it as easy as possible to contribute to Rig, we do have three policies that we advise contributors to stick to:

  • Use docstrings on any new public items (structs, enums, methods whether free-standing or associated).
  • Ensure that you use full syntax for trait bounds where possible. This makes the code much easier to read.
  • If your PR adds additional functionality to Rig, it must include relevant tests that pass (if the code does not directly interact with an API model provider), or alternatively an example that compiles if the code is user-facing.

As a contributor, you are additionally welcome to use AI assistance for coding. However to make the review process as smooth as possible, it's helpful to keep in mind the following:

  • You as a contributor are responsible for ensuring correctness, maintainability and compliance with project standards. Using AI does not change the quality bar.
  • Please make it clear in the PR description that it was significantly or 100% generated by AI if it is the case. Adding a short note like "This PR was generated by Claude" to your PR description is generally sufficient.

AI-generated PRs may require additional review to ensure correctness and long-term maintainability, including possible code style clean-up.

Other than that, each PR will be taken on a case-by-case basis.

PRs that will be rejected

As with every open source repo, not every contribution is within the scope of the repo and as Rig grows, so will the number of potential contributions - which also means defining an absolute list of things that are not within the scope of Rig. This includes but is not limited to:

  • Changes that would force model provider integrations to diverge from the original API (eg attempting to add a field to the OpenAI API that does not actually exist within the OpenAI API for the sake of satisfying another model provider)
  • PRs with arbitrary markdown files. The only markdown files we currently allow are ones that are already traditional convention (DEVELOPING.md, CONTRIBUTIONS.md, ARCHITECTURE.md, ... etc)
  • PRs that are found to be duplicates of other PRs

This will be reviewed on a case by case basis, but generally unjustifiable breaking changes are much more likely to be rejected.

Project Structure

Rig is split up into multiple crates in a monorepo structure. The main crate rig-core contains all of the foundational abstractions for building with LLMs. This crate avoids adding many new dependencies to keep to lean and only really contains simple provider integrations on top of the base layer of abstractions. Side crates are leveraged to help add important first-party behavior without over burdening the main library with dependencies. For example, rig-mongodb contains extra dependencies to be able to interact with mongodb as a vector store.

If you are unsure whether a side-crate should live in the main repo, you can spin up a personal repo containing your crate and create an issue in our repo making the case on whether this side-crate should be integrated in the main repo and maintained by the Rig team.

Developing

Setup

This should be similar to most Rust projects.

git clone https://github.com/0xplaygrounds/rig
cd rig
cargo test

Clippy and Fmt

We enforce both clippy and fmt for all pull requests.

cargo clippy --all-features --all-targets
cargo fmt -- --check

If you have the just task runner installed, you can also run just (or just ci).

Tests

Make sure to test against the test suite before making a pull request.

cargo test

Claude Code

If you're using Claude Code, don't forget to symlink AGENTS.md to CLAUDE.md:

ln -s AGENTS.md CLAUDE.md

If your filesystem or OS policy blocks symlinks, create a copy instead:

cp AGENTS.md CLAUDE.md

AI Agent Setup Matrix

Rig keeps one canonical AI instruction source in AGENTS.md. Agent-specific adapter files are generated from that source.

Agent Primary Files Setup Notes
Claude Code CLAUDE.md, .claude/skills/*/SKILL.md, .claude/commands/*.md CLAUDE.md is a symlink to AGENTS.md. Skills follow the Agent Skills standard. Legacy commands kept for backward compatibility.
GitHub Copilot / VS Code .github/copilot-instructions.md, .github/instructions/*.md, .github/prompts/*.prompt.md Copilot consumes repository instructions and prompt files in .github/.
Cursor .cursor/rules/*.mdc Cursor consumes rule files from .cursor/rules/.
Windsurf .windsurf/rules/*.md Windsurf consumes rule files from .windsurf/rules/.
Cline .clinerules/*.md Cline consumes rule files from .clinerules/ with path-based scoping.
Continue .continue/rules/*.md Continue consumes rule files with glob-based scoping.
Roo Code .roo/rules/*.md Roo Code consumes rule files from .roo/rules/.
Gemini CLI GEMINI.md GEMINI.md is a symlink to AGENTS.md.
Codex CLI / Zed / Aider AGENTS.md These tools read AGENTS.md directly.

Distributable Rig Skill

The skills/rig/ directory contains a usage-focused skill for developers building applications with Rig (as opposed to contributing to it).

One-liner install (auto-detects which agents you use):

curl -fsSL https://raw.githubusercontent.com/0xPlaygrounds/rig/main/scripts/install-rig-skill.sh | bash

Manual install for Claude Code:

cp -r skills/rig/ your-project/.claude/skills/rig/

Install for a specific agent (claude, cursor, copilot, windsurf, cline, continue, roo, gemini, agents-md):

curl -fsSL https://raw.githubusercontent.com/0xPlaygrounds/rig/main/scripts/install-rig-skill.sh | bash -s -- --agent cursor

Install for all agents:

curl -fsSL https://raw.githubusercontent.com/0xPlaygrounds/rig/main/scripts/install-rig-skill.sh | bash -s -- --all

Updating Agent Instructions

When updating AI guidance:

  1. Edit AGENTS.md only.
  2. Regenerate adapters: 
    scripts/sync_agent_instruction_files.sh
  3. Validate no drift: 
    scripts/validate_agent_instruction_files.sh
  4. Include regenerated adapter files in the same PR.

Manual Smoke-Test Checklist

Use this checklist for PR validation after updating agent instructions:

  1. Claude Code: invoke skills in .claude/skills/ (e.g., /rig-agent-scaffold, /rig-provider) and verify responses retain builder pattern, trait abstraction, and quality gates.
  2. Cursor: confirm .cursor/rules/*.mdc rules are discovered and influence Rust edit suggestions.
  3. Copilot/VS Code: confirm .github/copilot-instructions.md and .github/prompts/*.prompt.md are available and influence generated output.
  4. Windsurf: confirm .windsurf/rules/*.md rules are loaded.
  5. Cline: confirm .clinerules/*.md rules are loaded and path scoping works.
  6. Continue: confirm .continue/rules/*.md rules are loaded with glob matching.
  7. Roo Code: confirm .roo/rules/*.md rules are loaded.
  8. Gemini CLI: confirm GEMINI.md is loaded as project context.