Contributing

We welcome contributions to OpenConvert! This guide will help you get started with contributing to the project.

Getting Started

Development Environment Setup

  1. Fork and clone the repository:

    # Fork on GitHub, then clone your fork
git clone https://github.com/yourusername/openconvert.git
cd openconvert

  2. Set up development environment:

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

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

  3. Verify setup:

    # Run tests
pytest

# Check code formatting
black --check openconvert/
flake8 openconvert/

# Verify CLI works
openconvert --help

Development Workflow

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes

  3. Test your changes:

    # Run full test suite
pytest

# Run specific tests
pytest tests/test_client.py

# Check coverage
pytest --cov=openconvert --cov-report=html

  4. Format and lint code:

    # Format code
black openconvert/ tests/

# Check linting
flake8 openconvert/ tests/

# Type checking (if using mypy)
mypy openconvert/

  5. Commit and push:

    git add .
git commit -m "Add feature: description of your changes"
git push origin feature/your-feature-name

  6. Create a Pull Request

Types of Contributions

Bug Reports

Before submitting a bug report:

  1. Check existing issues - Search for similar issues

  2. Try the latest version - Bug might already be fixed

  3. Minimal reproduction - Create the smallest example that reproduces the issue

Good bug report includes:

  • Clear description of the problem

  • Steps to reproduce

  • Expected vs actual behavior

  • Environment details (OS, Python version, OpenConvert version)

  • Error messages and logs

  • Minimal code example

Bug report template:

**Bug Description**
A clear description of what the bug is.

**Steps to Reproduce**
1. Set up environment with...
2. Run command...
3. Observe error...

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Environment**
- OS: Ubuntu 22.04
- Python: 3.10.8
- OpenConvert: 1.0.0
- OpenAgents: (version)

**Error Output**
```
Paste error messages here
```

**Minimal Example**
```python
# Minimal code that reproduces the issue
from openconvert import convert_file
convert_file("test.txt", "test.pdf")
```

Feature Requests

For feature requests:

  1. Check roadmap - See if it’s already planned

  2. Discuss first - Open a discussion before implementing

  3. Consider scope - Start with small, focused features

Feature request template:

**Feature Description**
Clear description of the proposed feature.

**Use Case**
Why is this feature needed? What problem does it solve?

**Proposed Solution**
How should this feature work?

**Alternatives Considered**
What other approaches did you consider?

**Additional Context**
Any other relevant information.

Code Contributions

Areas where we need help:

  • New format support - Add support for additional file formats

  • Performance improvements - Optimize conversion speed and memory usage

  • Documentation - Improve guides, examples, and API docs

  • Testing - Add test cases and improve coverage

  • CLI enhancements - Better error messages, progress bars, etc.

  • Agent implementations - New conversion agents

  • Platform support - Windows, macOS compatibility improvements

Documentation

Documentation improvements are always welcome:

  • Fix typos and grammar

  • Add examples - Real-world usage examples

  • Improve clarity - Make explanations clearer

  • Add translations - Translate documentation to other languages

  • API documentation - Improve docstrings and auto-generated docs

Code Style and Standards

Python Code Style

We follow PEP 8 with some modifications:

# Good: Clear function names and docstrings
def convert_file_to_pdf(input_file: str, output_file: str) -> bool:
    """Convert a file to PDF format.

    Args:
        input_file: Path to input file
        output_file: Path to output PDF file

    Returns:
        True if conversion succeeded, False otherwise
    """
    # Implementation here
    pass

# Good: Type hints
from typing import Optional, List

def batch_convert(
    files: List[str],
    output_dir: str,
    format: Optional[str] = None
) -> List[bool]:
    """Convert multiple files."""
    results = []
    for file in files:
        # Process each file
        pass
    return results

Formatting tools:

  • Black - Code formatter (line length 88)

  • isort - Import sorting

  • flake8 - Linting

# Format code
black openconvert/ tests/
isort openconvert/ tests/

# Check style
flake8 openconvert/ tests/

Documentation Style

  • Use reStructuredText for documentation files

  • Clear headings - Use proper heading hierarchy

  • Code examples - Include working examples

  • Cross-references - Link to related sections

Example Function
~~~~~~~~~~~~~~~~

The :func:`convert_file` function converts files:

.. code-block:: python

   from openconvert import convert_file

   success = convert_file("input.txt", "output.pdf")

See also:

- :doc:`cli-reference` - Command line usage
- :doc:`../examples/batch-processing` - Batch examples

Commit Message Format

Use conventional commit format:

type(scope): description

Longer explanation if needed.

Fixes #issue-number

Types:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation changes

  • style: Code style changes (formatting, etc.)

  • refactor: Code refactoring

  • test: Adding or updating tests

  • chore: Maintenance tasks

Examples:

feat(cli): add progress bar for batch conversions

fix(client): handle connection timeout properly

docs(api): add examples for convert_file function

test(client): add unit tests for error handling

Testing Guidelines

Test Structure

tests/
├── unit/           # Unit tests
│   ├── test_client.py
│   ├── test_cli.py
│   └── test_utils.py
├── integration/    # Integration tests
│   ├── test_conversion.py
│   └── test_network.py
├── fixtures/       # Test data
│   ├── sample.txt
│   ├── sample.pdf
│   └── sample.jpg
└── conftest.py     # Pytest configuration

Writing Tests

import pytest
from unittest.mock import patch, MagicMock
from openconvert import convert_file
from openconvert.client import OpenConvertClient

class TestConvertFile:
    """Test the convert_file function."""

    @patch('openconvert.client.OpenConvertClient')
    def test_successful_conversion(self, mock_client_class):
        """Test successful file conversion."""
        # Setup mock
        mock_client = MagicMock()
        mock_client_class.return_value = mock_client
        mock_client.convert_file.return_value = True

        # Test
        result = convert_file("test.txt", "test.pdf")

        # Assert
        assert result is True
        mock_client.convert_file.assert_called_once()

    def test_file_not_found(self):
        """Test handling of missing input file."""
        with pytest.raises(FileNotFoundError):
            convert_file("missing.txt", "output.pdf")

    @pytest.mark.integration
    def test_real_conversion(self, test_network):
        """Integration test with real network."""
        # This test requires a running network
        result = convert_file("fixtures/sample.txt", "output.pdf")
        assert result is True

Test categories:

  • Unit tests - Test individual functions/classes

  • Integration tests - Test component interactions

  • End-to-end tests - Test complete workflows

  • Performance tests - Test speed and resource usage

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/unit/test_client.py

# Run tests by marker
pytest -m "not integration"  # Skip integration tests
pytest -m integration        # Only integration tests

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

# Run performance tests
pytest --benchmark-only

Review Process

Pull Request Guidelines

Before submitting:

  1. Rebase on main - Keep history clean

  2. Run full test suite - Ensure all tests pass

  3. Update documentation - If adding features

  4. Add tests - For new functionality

  5. Check CI - Ensure all checks pass

Pull request template:

## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Other (specify)

## Testing
- [ ] Added unit tests
- [ ] Added integration tests
- [ ] Manual testing performed
- [ ] All existing tests pass

## Documentation
- [ ] Updated API documentation
- [ ] Updated user guides
- [ ] Added examples

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated

Review Criteria

Reviewers check for:

  • Functionality - Does it work as intended?

  • Code quality - Is it maintainable and readable?

  • Performance - Any performance implications?

  • Security - Any security concerns?

  • Testing - Adequate test coverage?

  • Documentation - Clear documentation?

  • Compatibility - Breaks existing functionality?

Community Guidelines

Code of Conduct

We follow the Contributor Covenant Code of Conduct:

  • Be respectful - Treat everyone with respect

  • Be inclusive - Welcome newcomers and diverse perspectives

  • Be constructive - Provide helpful feedback

  • Be patient - Help others learn and grow

Communication Channels

  • GitHub Issues - Bug reports and feature requests

  • GitHub Discussions - General questions and ideas

  • Discord - Real-time chat and support

  • Pull Requests - Code review discussions

Getting Help

If you need help contributing:

  1. Read the documentation - Start with this guide

  2. Search existing issues - Your question might be answered

  3. Ask in discussions - Post in GitHub Discussions

  4. Join Discord - Get real-time help from community

  5. Mention maintainers - Tag maintainers in issues if stuck

Recognition

Contributors are recognized through:

  • Contributors list - Added to README and documentation

  • Release notes - Mentioned in release announcements

  • Badges - GitHub profile badges for contributions

  • Maintainer nomination - Outstanding contributors may be invited as maintainers

Release Process

For maintainers:

  1. Version bumping - Update version in setup.py

  2. Changelog - Update CHANGELOG.md

  3. Documentation - Update version in docs/conf.py

  4. Testing - Run full test suite

  5. Tagging - Create git tag

  6. Release - Publish to PyPI

  7. Announcement - Post release notes

# Release checklist
git checkout main
git pull origin main

# Update version and changelog
# Run tests
pytest

# Create tag
git tag v1.1.0
git push origin v1.1.0

# Build and publish
python setup.py sdist bdist_wheel
twine upload dist/*

Thank You!

Thank you for contributing to OpenConvert! Every contribution, whether it’s code, documentation, bug reports, or feature suggestions, helps make the project better for everyone.

See Also