docs: replace CONTRIBUTING.md and clean up README
- Replace old CONTRIBUTING.md with comprehensive contributing guide - Remove fork notice from README header
This commit is contained in:
340
CONTRIBUTING.md
340
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)
|
- [Code of Conduct](#code-of-conduct)
|
||||||
- [Commit Message Format](#commit-message-format)
|
- [Getting Started](#getting-started)
|
||||||
|
- [Development Environment Setup](#development-environment-setup)
|
||||||
---
|
- [How to Contribute](#how-to-contribute)
|
||||||
|
- [Coding Standards](#coding-standards)
|
||||||
## Getting Started
|
- [Testing](#testing)
|
||||||
|
- [Pull Request Process](#pull-request-process)
|
||||||
### Requirements
|
- [Reporting Bugs](#reporting-bugs)
|
||||||
|
- [Suggesting Features](#suggesting-features)
|
||||||
- [Rust](https://www.rust-lang.org/tools/install): v1
|
- [AI Usage Policy](#ai-usage-policy)
|
||||||
|
- [Questions?](#questions)
|
||||||
### 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.
|
|
||||||
|
|
||||||
## Code of Conduct
|
## 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.
|
||||||
|
|||||||
@@ -2,9 +2,6 @@
|
|||||||
|
|
||||||
Rust client for the [Mistral AI API](https://docs.mistral.ai/api/).
|
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
|
## Supported APIs
|
||||||
|
|
||||||
- [x] Chat completions (sync, async, streaming)
|
- [x] Chat completions (sync, async, streaming)
|
||||||
|
|||||||
Reference in New Issue
Block a user