Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
231 lines (158 loc) · 4.87 KB

CONTRIBUTING.md

File metadata and controls

231 lines (158 loc) · 4.87 KB
Raw

Contributing to otari (Rust)

Thank you for your interest in contributing to otari!

We're building a simple, unified Rust interface for working with LLMs through the Otari gateway, and we welcome contributions from developers of all experience levels.

Before You Start

Check for Duplicates

Before creating a new issue or starting work:

Discuss Major Changes First

For significant changes, please open an issue before starting work:

  • API changes or new public methods
  • Breaking changes
  • New dependencies

Development Setup

Prerequisites

  • Rust 1.83 or newer (rustup update stable)
  • Git
  • A running Otari gateway instance for integration tests

Quick Start

# 1. Fork the repository on GitHub

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/otari-sdk-rust.git
cd otari-sdk-rust

# 3. Add upstream remote
git remote add upstream https://github.com/mozilla-ai/otari-sdk-rust.git

# 4. Build the project
cargo build

# 5. Run tests
cargo test

# 6. Run lints
cargo clippy --all-features --all-targets -- -D warnings

# 7. Format code
cargo fmt

Setting Up API Keys

Create a .env file in the project root (this file is gitignored):

OTARI_API_KEY=your_key_here
OTARI_API_BASE=http://localhost:8000

Or export environment variables:

export OTARI_API_KEY="your_key_here"
export OTARI_API_BASE="http://localhost:8000"

Never commit API keys!

Making Changes

1. Create a Branch

Always work on a feature branch:

# Update your main branch
git checkout main
git pull upstream main

# Create a new branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Branch naming conventions:

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code improvements

2. Code Style

We use strict Clippy lints. Before committing:

# Format code
cargo fmt

# Run clippy
cargo clippy --all-features --all-targets -- -D warnings

# Run tests
cargo test --all-features

3. Write Tests

Every change needs tests!

  • New features: Add tests covering happy path and error cases
  • Bug fixes: Add a test that reproduces the bug

Tests are organized as:

  • src/ - Unit tests in #[cfg(test)] modules
  • tests/ - Integration tests

4. Documentation

Update documentation when you:

  • Add a new feature
  • Change existing behavior

Documentation to update:

  • Doc comments (///) on public items (required)
  • README.md if changing core functionality
  • Examples in examples/ directory

5. Commit Messages

Write clear, descriptive commit messages:

# Good
git commit -m "feat: add batch operation support"
git commit -m "fix: handle streaming disconnect gracefully"

# Less helpful (avoid)
git commit -m "fix bug"
git commit -m "update"

Submitting Your Contribution

1. Push to Your Fork

git add .
git commit -m "feat: add support for new feature"
git push origin feature/your-feature-name

2. Create a Pull Request

  1. Go to the repository on GitHub
  2. Click "New Pull Request"
  3. Select your fork and branch
  4. Fill out the PR description completely
  5. Ensure CI passes

Review Process

What to Expect

  1. Initial Response: Within 5 business days
  2. Simple Fixes: Usually merged within 1 week
  3. Complex Features: May take 2-3 weeks

During Review

  • Maintainers will provide constructive feedback
  • Address comments with new commits
  • CI must pass before merge

Your First Contribution

New to the project? Look for issues labeled:

  • good-first-issue - Perfect for newcomers
  • help-wanted - Community contributions welcome
  • documentation - Often accessible for beginners

Starter Ideas

  • Fix a typo in documentation
  • Add a test case
  • Improve error messages
  • Add an example

Development Commands

# Build
cargo build
cargo build --all-features

# Test
cargo test                          # All tests
cargo test --lib                    # Unit tests only
cargo test --test '*'               # Integration tests only
cargo test test_name                # Specific test

# Lint
cargo clippy --all-features --all-targets -- -D warnings

# Format
cargo fmt
cargo fmt --check                   # Check only

# Documentation
cargo doc --all-features --no-deps --open

# Run example
cargo run --example gateway_completion

Questions?

  • Open a GitHub Issue for bugs or feature requests
  • Start a Discussion for questions

We're excited to have you contribute!

License: By contributing, you agree that your contributions will be licensed under the Apache License 2.0.