mistralai-client-rs/CONTRIBUTING.md

# Contributing to mistralai-client-rs

Thank you for your interest in contributing! We're excited to work with you.

This document provides guidelines for contributing to the project. Following these guidelines helps maintain code quality and makes the review process smoother for everyone.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Environment Setup](#development-environment-setup)
- [How to Contribute](#how-to-contribute)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Pull Request Process](#pull-request-process)
- [Reporting Bugs](#reporting-bugs)
- [Suggesting Features](#suggesting-features)
- [AI Usage Policy](#ai-usage-policy)
- [Questions?](#questions)

## Code of Conduct

This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

## Getting Started

1. **Fork the repository** on Gitea
2. **Clone your fork** locally
3. **Set up your development environment** (see below)
4. **Create a branch** for your changes
5. **Make your changes** with clear commit messages
6. **Test your changes** thoroughly
7. **Submit a pull request**

## Development Environment Setup

### Prerequisites

- **Rust** 2024 edition or later (install via [rustup](https://rustup.rs/))
- **Git** for version control

### Initial Setup

```bash
# Clone your fork
git clone git@src.sunbeam.pt:studio/mistralai-client-rs.git
cd mistralai-client-rs

# Build the project
cargo build

# Run tests (requires MISTRAL_API_KEY)
cargo test
```

### Useful Commands

```bash
# Check code without building
cargo check

# Run clippy for linting
cargo clippy

# Format code
cargo fmt

# Run tests with output
cargo test -- --nocapture

# Build documentation
cargo doc --open
```

### Environment Variables with `.envrc`

This project uses [direnv](https://direnv.net/) for managing environment variables.

#### Setup

1. **Install direnv** (if not already installed):
   ```bash
   # macOS
   brew install direnv

   # Add to your shell profile (~/.zshrc or ~/.bashrc)
   eval "$(direnv hook zsh)"  # or bash
   ```

2. **Create `.envrc` file** in the project root:
   ```bash
   # The .envrc file is already gitignored for security
   export MISTRAL_API_KEY=your_api_key_here
   ```

3. **Allow direnv** to load the file:
   ```bash
   direnv allow .
   ```

## How to Contribute

### Types of Contributions

We welcome many types of contributions:

- **Bug fixes** - Fix issues and improve stability
- **Features** - Implement new functionality (discuss first in an issue)
- **Documentation** - Improve or add documentation
- **Examples** - Create new examples or demos
- **Tests** - Add test coverage
- **Performance** - Optimize existing code
- **Refactoring** - Improve code quality

### Before You Start

For **bug fixes and small improvements**, feel free to open a PR directly.

For **new features or significant changes**:
1. **Open an issue first** to discuss the proposal
2. Wait for maintainer feedback before investing significant time
3. Reference the issue in your PR

This helps ensure your work aligns with project direction and avoids duplicate effort.

## Coding Standards

### Rust Style

- Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Use `cargo fmt` to format code (run before committing)
- Address all `cargo clippy` warnings
- Use meaningful variable and function names
- Add doc comments (`///`) for public APIs

### Code Organization

- Keep modules focused and cohesive
- Prefer composition over inheritance
- Use Rust's type system to enforce invariants
- Avoid unnecessary `unsafe` code

### Documentation

- Add doc comments for all public types, traits, and functions
- Include examples in doc comments when helpful
- Keep README.md in sync with current capabilities

### Commit Messages

This repository follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.

Write clear, descriptive commit messages:

```
feat: add batch jobs API

fix: handle empty tool_calls in streaming response

refactor!: replace Model enum with string-based type

BREAKING CHANGE: Model is now a struct, not an enum.
```

## Testing

### Running Tests

```bash
# Run all tests (requires MISTRAL_API_KEY)
cargo test

# Run specific test
cargo test test_client_chat

# Run tests with output
cargo test -- --nocapture
```

### Writing Tests

- Add unit tests in the same file as the code (in a `mod tests` block)
- Add integration tests in `tests/` directory
- Test edge cases and error conditions
- Keep tests focused and readable
- Use descriptive test names

### Test Coverage

Tests hit the live Mistral API, so a valid `MISTRAL_API_KEY` is required. The tests use small, cheap models and consume minimal tokens.

## Pull Request Process

### Before Submitting

1. **Update your branch** with latest upstream changes
   ```bash
   git fetch origin
   git rebase origin/main
   ```

2. **Run the test suite** and ensure all tests pass
   ```bash
   cargo test
   ```

3. **Run clippy** and fix any warnings
   ```bash
   cargo clippy
   ```

4. **Format your code**
   ```bash
   cargo fmt
   ```

5. **Update documentation** if you changed APIs or behavior

### Submitting Your PR

1. **Push to your fork**
2. **Open a pull request** on Gitea
3. **Fill out the PR description** with what changed and why
4. **Request review** from maintainers

### During Review

- Be responsive to feedback
- Make requested changes promptly
- Push updates to the same branch
- Be patient - maintainers are volunteers with limited time

## Reporting Bugs

### Before Reporting

1. **Check existing issues** to avoid duplicates
2. **Verify it's a bug** and not expected behavior
3. **Test on the latest version** from main branch

### Bug Report Template

When opening a bug report, please include:

- **Description** - What went wrong?
- **Expected behavior** - What should have happened?
- **Actual behavior** - What actually happened?
- **Steps to reproduce** - Minimal steps to reproduce the issue
- **Environment**:
  - OS version
  - Rust version (`rustc --version`)
  - Crate version or commit hash
- **Logs/Stack traces** - Error messages or relevant log output

## Suggesting Features

We welcome feature suggestions! When suggesting a feature, please include:

- **Problem statement** - What problem does this solve?
- **Proposed solution** - How would this feature work?
- **Alternatives considered** - What other approaches did you think about?
- **Use cases** - Real-world scenarios where this helps

## AI Usage Policy

- AI tools (Copilot, ChatGPT, etc.) are allowed for productivity
- You must understand and be accountable for all code you submit
- Humans make all architectural decisions, not AI
- When in doubt, ask yourself: "Can I maintain and debug this?"

## Questions?

Open an issue on the repository for any questions about contributing.

---

Thank you for contributing! Your effort helps make this library better for everyone.