mistral-ocr/CONTRIBUTING.md

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
  • Table of Contents
  • Code of Conduct
  • Getting Started
    • Development Environment Setup
    • Project Structure
  • Development Workflow
    • Creating a Feature
    • Testing
    • Documentation
  • Pull Request Process
  • Coding Standards
  • 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:

   git clone https://github.com/yourusername/mistral-ocr-python.git
   cd mistral-ocr-python
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install the package in development mode:

   pip install -e .
   

4. Install development dependencies:

   pip install pytest pytest-cov black flake8
   

Project Structure

mistral-ocr-python/
├── 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:

   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:

   git add .
   git commit -m "Add feature: your feature description"
   

Testing

We use pytest for testing. To run the tests:

python -m pytest

For coverage report:

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:

   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:

black mistral_ocr

For linting:

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!