CONTRIBUTING.md

Contributing Guide

This document describes how to set up the development environment and use code quality tools.

Development Setup

1. Install Dependencies

# Install core dependencies
pip install -r requirements.txt

# Or install with dev dependencies (if using pyproject.toml)
pip install -e ".[dev]"

2. Code Quality Tools

This project uses several tools to maintain code quality:

• Ruff: Fast Python linter and formatter (replaces Black, flake8, isort, etc.)
• MyPy: Static type checker

Ruff

Ruff is configured via ruff.toml. It combines the functionality of multiple linters (flake8, isort, Black, etc.) and is used for both linting and formatting.

# Check for issues
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

# Check formatting without making changes
ruff format --check .

MyPy

MyPy is configured via .mypy.ini and pyproject.toml.

# Type check
mypy email_processor

3. Pre-commit Hooks (Required)

Pre-commit hooks automatically run code quality checks before each commit. It is required to run pre-commit checks before committing and pushing.

# Install pre-commit
pip install pre-commit

# Install git hooks (optional - hooks will run automatically on commit)
pre-commit install

# Run hooks manually (REQUIRED before commit and push)
pre-commit run --all-files

Note: Even if hooks are installed, always run pre-commit run --all-files manually before committing to ensure all checks pass.

4. Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=email_processor --cov-report=html

# Run specific test file
pytest tests/unit/imap/test_fetcher_header.py

# Run all fetcher tests
pytest tests/unit/imap/test_fetcher_*.py

# Run specific test category
pytest tests/unit/imap/test_fetcher_attachment.py

5. Code Quality Workflow

⚠️ IMPORTANT: Before committing and pushing, always run these checks:

1. Check formatting (required):

   ruff format --check .

   If files need formatting, run:

   ruff format .

2. Run pre-commit checks (required):

   pre-commit run --all-files

   This will run all hooks including:

   • Trailing whitespace check
   • End of file fixer
   • Ruff linting and formatting
   • Ruff check (full project check)
   • MyPy type checking

3. Lint code (if pre-commit didn't fix everything):

   ruff check --fix .

4. Type check (optional, also runs in pre-commit):

   mypy email_processor

5. Run tests:

   pytest

Recommended workflow:

# 1. Check formatting first
ruff format --check .

# 2. If needed, format code
ruff format .

# 3. Run all pre-commit checks
pre-commit run --all-files

# 4. Run tests
pytest

# 5. Only then commit and push
git add .
git commit -m "your message"
git push

6. IDE Integration

VS Code

Add to .vscode/settings.json:

{
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.organizeImports": true,
      "source.fixAll": true
    }
  }
}

PyCharm

1. Install Ruff plugin
2. Configure Ruff as formatter and linter
3. Enable MyPy inspection

Configuration Files

• ruff.toml - Ruff linter and formatter configuration
• pyproject.toml - MyPy and project metadata
• .mypy.ini - MyPy type checker configuration
• .pre-commit-config.yaml - Pre-commit hooks configuration
• pytest.ini - Pytest test configuration

Code Style

• Line length: 100 characters
• Target Python version: 3.9+
• Type hints: Recommended but not required
• Docstrings: Use Google style for public APIs

Commit Messages

Follow conventional commits format:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Test additions/changes
• chore: Maintenance tasks

Example:

feat: add request ID and correlation ID to logs
fix: improve error handling with specific exceptions