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
• Getting Started
• Development Environment Setup
• How to Contribute
• Coding Standards
• Testing
• Pull Request Process
• Reporting Bugs
• Suggesting Features
• AI Usage Policy
• Questions?

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. 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)
• Git for version control

Initial Setup

# 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

# 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 for managing environment variables.

Setup

1. Install direnv (if not already installed):

   # 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:

   # The .envrc file is already gitignored for security
   export MISTRAL_API_KEY=your_api_key_here
   

3. Allow direnv to load the file:

   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
• 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 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

# 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

   git fetch origin
   git rebase origin/main
   

2. Run the test suite and ensure all tests pass

   cargo test
   

3. Run clippy and fix any warnings

   cargo clippy
   

4. Format your code

   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.