From ab2ecec351d988f3477d354488dd21e1ba99741b Mon Sep 17 00:00:00 2001 From: Sienna Meridian Satterwhite Date: Fri, 20 Mar 2026 18:08:40 +0000 Subject: [PATCH] docs: replace CONTRIBUTING.md and clean up README - Replace old CONTRIBUTING.md with comprehensive contributing guide - Remove fork notice from README header --- CONTRIBUTING.md | 340 ++++++++++++++++++++++++++++++++++++++---------- README.md | 3 - 2 files changed, 270 insertions(+), 73 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6f00f4..f354d00 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,77 +1,277 @@ -# Contribute +# 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 -- [Getting Started](#getting-started) - - [Requirements](#requirements) - - [First setup](#first-setup) - - [Optional requirements](#optional-requirements) -- [Local Development](#local-development) - - [Test](#test) -- [Documentation](#documentation) - - [Readme](#readme) - [Code of Conduct](#code-of-conduct) -- [Commit Message Format](#commit-message-format) - ---- - -## Getting Started - -### Requirements - -- [Rust](https://www.rust-lang.org/tools/install): v1 - -### First setup - -> [!IMPORTANT] -> If you're under **Windows**, you nust run all CLI commands under a Linux shell-like terminal (i.e.: WSL or Git Bash). - -Then run: - -```sh -git clone https://github.com/ivangabriele/mistralai-client-rs.git # or your fork -cd ./mistralai-client-rs -cargo build -cp .env.example .env -``` - -Then edit the `.env` file to set your `MISTRAL_API_KEY`. - -> [!NOTE] -> All tests use either the `open-mistral-7b` or `mistral-embed` models and only consume a few dozen tokens. -> So you would have to run them thousands of times to even reach a single dollar of usage. - -### Optional requirements - -- [cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov?tab=readme-ov-file#installation) for `make test-cover` -- [cargo-watch](https://github.com/watchexec/cargo-watch#install) for `make test-watch`. - -## Local Development - -### Test - -```sh -make test -``` - -or - -```sh -make test-watch -``` - -## Documentation - -### Readme - -> [!IMPORTANT] -> Do not edit the `README.md` file directly. It is generated from the `README.template.md` file. - -1. Edit the `README.template.md` file. -2. Run `make readme` to generate/update the `README.md` file. +- [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 -Help us keep this project open and inclusive. Please read and follow our [Code of Conduct](./CODE_OF_CONDUCT.md). +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. -## Commit Message Format +## Getting Started -This repository follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. +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. diff --git a/README.md b/README.md index fd0b497..829cb3d 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,6 @@ Rust client for the [Mistral AI API](https://docs.mistral.ai/api/). -> **Fork** of [ivangabriele/mistralai-client-rs](https://github.com/ivangabriele/mistralai-client-rs), -> updated to the latest Mistral API with all current endpoints and models. - ## Supported APIs - [x] Chat completions (sync, async, streaming)