Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
256 lines (186 loc) · 5.31 KB

CONTRIBUTING.md

File metadata and controls

256 lines (186 loc) · 5.31 KB
Raw

Contributing to verso

Thank you for your interest in contributing to verso! This document provides guidelines and information for contributors.

Development Setup

Prerequisites

  • Python 3.10+
  • uv (recommended) or pip
  • just (optional, for task running)

Installation

# clone the repository
git clone https://github.com/example/verso.git
cd verso

# install with uv (recommended)
uv sync --all-extras

# or with pip
pip install -e ".[dev]"

Verify Setup

# run tests
uv run pytest tests/ -v

# or with just
just test

Development Workflow

Running Tests

# all tests
just test

# with coverage
just test-cov

# specific test file
just test-file tests/test_schema.py

# tests matching pattern
just test-match "test_heading"

Code Quality

# lint
just lint

# fix lint issues
just lint-fix

# format code
just fmt

# type check
just typecheck

# run all checks
just check

Pre-commit Hooks

We recommend using pre-commit hooks:

just pre-commit-install

Code Style

Python

  • Follow PEP 8
  • Use type hints for all public functions
  • Maximum line length: 88 characters (enforced by ruff)
  • Use double quotes for strings
  • Sort imports with isort (via ruff)

Docstrings

Use Google-style docstrings:

def extract(source: str, config: Config | None = None) -> Document:
    """Extract content from a document.

    Args:
        source: Path to the document file.
        config: Optional configuration object.

    Returns:
        Document object containing extracted content.

    Raises:
        ValueError: If the file format is not supported.
    """

Commit Messages

Use conventional commits:

  • feat: new feature
  • fix: bug fix
  • docs: documentation changes
  • test: test changes
  • refactor: code refactoring
  • perf: performance improvement
  • chore: maintenance tasks

Examples:

feat: add support for EPUB format
fix: correct heading detection for small fonts
docs: update API reference
test: add tests for list detection

Project Structure

verso/
├── src/verso/              # main package
│   ├── __init__.py         # public API
│   ├── cli.py              # command-line interface
│   ├── config.py           # configuration
│   ├── schema.py           # data structures
│   ├── structure.py        # structure detection
│   ├── pipeline.py         # processing pipeline
│   ├── analyzer.py         # document analysis
│   ├── detect.py           # format detection
│   ├── mcp_server.py       # MCP server
│   ├── providers/          # document providers
│   │   ├── pdf.py          # pdftext backend
│   │   ├── pdf_mupdf.py    # MuPDF backend
│   │   └── ...
│   ├── processors/         # content processors
│   ├── renderers/          # output renderers
│   └── backends/           # compute backends
├── tests/                  # test files
├── scripts/                # utility scripts
├── research/               # research documents
└── docs/                   # documentation

Adding Features

New Provider

  1. Create src/verso/providers/your_provider.py
  2. Implement BaseProvider interface
  3. Add format detection in src/verso/detect.py
  4. Register in src/verso/providers/__init__.py
  5. Add tests in tests/test_your_provider.py

New Processor

  1. Create processor in src/verso/processors/
  2. Implement BaseProcessor interface
  3. Integrate into pipeline
  4. Add tests

New Renderer

  1. Create renderer in src/verso/renderers/
  2. Implement BaseRenderer interface
  3. Add output format option
  4. Add tests

Testing Guidelines

Test Structure

class TestFeatureName:
    def test_basic_case(self):
        """Test the most common use case."""
        ...

    def test_edge_case(self):
        """Test edge cases."""
        ...

    def test_error_handling(self):
        """Test error conditions."""
        ...

Test Data

  • Use fixtures for common test data
  • Keep test PDFs small (<100KB)
  • Use tempfile for generated files
  • Clean up resources in teardown

Markers

@pytest.mark.slow           # slow tests
@pytest.mark.integration    # integration tests

Pull Request Process

  1. Fork the repository
  2. Create a feature branch from main
  3. Make your changes
  4. Ensure all tests pass: just check
  5. Update documentation if needed
  6. Update CHANGELOG.md
  7. Submit pull request

PR Checklist

  • Tests pass locally
  • Code is formatted and linted
  • Type hints are complete
  • Docstrings are updated
  • CHANGELOG.md is updated
  • No breaking changes (or documented)

Release Process

Releases are automated via GitHub Actions:

  1. Update version in src/verso/__init__.py
  2. Update CHANGELOG.md
  3. Create a GitHub release
  4. CI publishes to PyPI

Getting Help

  • Open an issue for bugs or feature requests
  • Start a discussion for questions
  • Check existing issues before creating new ones

Code of Conduct

Be respectful and inclusive. We follow the Contributor Covenant.

License

By contributing, you agree that your contributions will be licensed under the MIT License.