# 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](https://docs.rig.rs/docs/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 its 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](https://conventionalcommits.org/en/v1.0.0) format (prefixing with `feat`, `fix`, etc.) as this integrates into our auto-releases via a [release-plz](https://github.com/MarcoIeni/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:
```md
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](https://kcd.im/pull-request)

### 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 welcome to use AI assistance for coding. Using AI does not change the quality bar or transfer responsibility away from you.

You are entirely accountable for any code generated by an AI agent. The pull request you submit represents your work, regardless of how much was AI-assisted. Reviewers will hold you to the same quality standards as any other contributor. "The AI wrote it" is not an acceptable excuse for poor code quality, missing error handling, or incomplete implementations.

Before submitting any AI-assisted PR:

1. Review every line of generated code.
2. Ensure you understand what it does and why.
3. Verify it meets all contribution guidelines.
4. Test it thoroughly.
5. Explain any significant AI assistance in the PR description.

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)
- Lazy workarounds such as `String` error types, scattered `.unwrap()` calls, stubbed error handling, or incomplete edge-case handling
- TODO comments, placeholder implementations, or `unimplemented!()` in submitted code
- Missing WASM compatibility where `WasmCompatSend` or `WasmCompatSync` should be used instead of raw `Send` or `Sync`
- Unclear code that needs comments to explain what it is doing instead of being refactored for readability
- Major architectural changes, new abstractions, or public API reshaping without prior discussion
- 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.

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

### Clippy and Fmt

We enforce both `clippy` and `fmt` for all pull requests.

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

### Tests

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

```bash
cargo test
```

## AI Agent Instructions

Rig keeps one canonical AI instruction source in `AGENTS.md`.

When updating AI guidance:

1. Edit `AGENTS.md`.
2. Keep `.github` instruction and prompt files aligned when GitHub-specific guidance changes.
3. Do not add generated adapter directories for unsupported tools.
