# Contributing to Mistral OCR CLI

Thank you for your interest in contributing to Mistral OCR CLI! This document provides guidelines and instructions for contributing to this project.

## Table of Contents

- [Contributing to Mistral OCR CLI](#contributing-to-mistral-ocr-cli)
  - [Table of Contents](#table-of-contents)
  - [Code of Conduct](#code-of-conduct)
  - [Getting Started](#getting-started)
    - [Development Environment Setup](#development-environment-setup)
    - [Project Structure](#project-structure)
  - [Development Workflow](#development-workflow)
    - [Creating a Feature](#creating-a-feature)
    - [Testing](#testing)
    - [Documentation](#documentation)
  - [Pull Request Process](#pull-request-process)
  - [Coding Standards](#coding-standards)
  - [Release Process](#release-process)

## Code of Conduct

Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community.

## Getting Started

### Development Environment Setup

1. **Fork and clone the repository**:
   ```bash
   git clone https://github.com/yourusername/mistral-ocr.git
   cd mistral-ocr
   ```

2. **Create a virtual environment**:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install the package in development mode**:
   ```bash
   pip install -e .
   ```

4. **Install development dependencies**:
   ```bash
   pip install pytest pytest-cov black flake8
   ```

### Project Structure

```
mistral-ocr/
├── mistral_ocr/              # Main package
│   ├── __init__.py
│   ├── __main__.py           # CLI entry point
│   ├── client.py             # Mistral API client
│   └── commands/             # Command implementations
│       ├── __init__.py
│       ├── convert.py        # Convert command
│       ├── markdown.py       # Markdown command
│       ├── process.py        # Process command
│       └── version.py        # Version command
├── tests/                    # Test directory
├── .gitignore
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── requirements.txt
├── setup.py
└── build.sh
```

## Development Workflow

### Creating a Feature

1. **Create a new branch**:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes**:
   - Implement your feature or fix
   - Add or update tests as necessary
   - Update documentation to reflect your changes

3. **Commit your changes**:
   ```bash
   git add .
   git commit -m "Add feature: your feature description"
   ```

### Testing

We use pytest for testing. To run the tests:

```bash
python -m pytest
```

For coverage report:

```bash
python -m pytest --cov=mistral_ocr
```

Please ensure that your code is well-tested and that all tests pass before submitting a pull request.

### Documentation

- Update the README.md if your changes affect the usage of the tool
- Add docstrings to your code following the Google style guide
- Update or add examples if necessary

## Pull Request Process

1. **Push your changes to your fork**:
   ```bash
   git push origin feature/your-feature-name
   ```

2. **Create a pull request** from your fork to the main repository

3. **Describe your changes** in the pull request:
   - What does this PR add or fix?
   - Any breaking changes?
   - Any dependencies added?

4. **Address review comments** if any are provided

5. **Your PR will be merged** once it's approved

## Coding Standards

We follow PEP 8 and use Black for code formatting:

```bash
black mistral_ocr
```

For linting:

```bash
flake8 mistral_ocr
```

General guidelines:

- Use descriptive variable and function names
- Add type hints to function signatures
- Write docstrings for all functions, classes, and modules
- Keep functions small and focused on a single task
- Use comments to explain complex logic

## Release Process

Releases are managed by the project maintainers. If you'd like to propose a release:

1. Update the version number in:
   - `mistral_ocr/commands/version.py`
   - `setup.py`

2. Update the CHANGELOG.md with the changes in the new version

3. Create a pull request with these changes

4. Once merged, the maintainers will create a new release tag

Thank you for contributing to Mistral OCR CLI!