Contributing

Thank you for your interest in contributing to the WTF Transcript Converter! This document provides guidelines and information for contributors.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

Python 3.10+ (3.12 recommended)
uv package manager
Git

Fork and Clone

Fork the repository on GitHub
Clone your fork locally:

git clone https://github.com/your-username/wtf-transcript-converter.git
cd wtf-transcript-converter

Development Setup

Quick Setup

# Install development dependencies
make setup-dev

# Or manually:
uv sync --dev
uv run pre-commit install

Verify Installation

# Run tests to verify everything works
make test

# Run cross-provider tests
make cross-provider-all

Contributing Guidelines

Types of Contributions

We welcome several types of contributions:

Bug Fixes: Fix issues in existing code
New Features: Add new functionality
Provider Integrations: Add support for new transcription providers
Documentation: Improve documentation and examples
Testing: Add or improve tests
Performance: Optimize existing code

Development Workflow

Create a branch:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number

Make your changes: * Write code following our style guidelines * Add tests for new functionality * Update documentation as needed
Test your changes:

make check          # Run linting, type checking, security
make test-all       # Run all tests
make cross-provider-all  # Run cross-provider tests

Commit your changes:

git add .
git commit -m "feat: add new provider integration"

Push and create PR:

git push origin feature/your-feature-name

Provider Integration

Adding a New Provider

To add support for a new transcription provider:

Create the converter:

# Create new provider file
touch src/wtf_transcript_converter/providers/new_provider.py

Implement the converter:

from wtf_transcript_converter.providers.base import BaseProviderConverter
from wtf_transcript_converter.core.models import WTFDocument

class NewProviderConverter(BaseProviderConverter):
    provider_name: str = "new_provider"
    description: str = "New Provider Description"
    status: str = "Implemented"

    def __init__(self, provider_name: str = "new_provider"):
        super().__init__(provider_name)

    def convert_to_wtf(self, data: Dict[str, Any]) -> WTFDocument:
        # Implementation here
        pass

    def convert_from_wtf(self, wtf_doc: WTFDocument) -> Dict[str, Any]:
        # Implementation here
        pass

Add to providers module:

# Update src/wtf_transcript_converter/providers/__init__.py
from .new_provider import NewProviderConverter

__all__ = [
    # ... existing providers
    "NewProviderConverter",
]

Update CLI:

# Update src/wtf_transcript_converter/cli/main.py
from ..providers.new_provider import NewProviderConverter

def _get_converter(provider: str):
    # ... existing providers
    elif provider == "new-provider":
        return NewProviderConverter()

Add tests:

# Create test file
touch tests/test_providers/test_new_provider.py

Update documentation: * Update README.md with new provider * Add usage examples * Update provider list in CLI

Provider Testing Requirements

Each provider must have:

[ ] Unit tests for convert_to_wtf()
[ ] Unit tests for convert_from_wtf()
[ ] Integration tests (if API available)
[ ] Cross-provider consistency tests
[ ] Error handling tests
[ ] Sample data fixtures

Testing

Test Structure

tests/
├── test_providers/          # Provider-specific tests
├── test_cross_provider/     # Cross-provider testing
├── test_integration/        # Integration tests
├── test_cli/               # CLI tests
├── fixtures/               # Test data
└── conftest.py            # Test configuration

Running Tests

# Run all tests
make test-all

# Run specific test categories
make test                    # Unit tests
make test-integration        # Integration tests
make test-cross-provider     # Cross-provider tests

# Run with coverage
make test-cov

# Run specific test file
uv run pytest tests/test_providers/test_whisper.py -v

Writing Tests

import pytest
from wtf_transcript_converter.providers.whisper import WhisperConverter

class TestWhisperConverter:
    def test_convert_to_wtf(self, sample_whisper_data):
        converter = WhisperConverter()
        wtf_doc = converter.convert_to_wtf(sample_whisper_data)

        assert wtf_doc.transcript.text == "expected text"
        assert wtf_doc.transcript.language == "en"
        assert len(wtf_doc.segments) > 0

Code Style

Python Style

We use several tools to maintain code quality:

Black: Code formatting
isort: Import sorting
flake8: Linting
mypy: Type checking
bandit: Security scanning

Running Style Checks

# Run all style checks
make check

# Individual checks
make lint          # flake8, black, isort
make type-check    # mypy
make security      # bandit, safety

Pre-commit Hooks

Pre-commit hooks run automatically on commit:

# Install hooks
make pre-commit-install

# Run manually
make pre-commit

Code Style Guidelines

Line length: 99 characters
Import order: isort with black profile
Type hints: Required for all public functions
Docstrings: Google style for all public functions
Error handling: Use specific exceptions, not bare except:

Pull Request Process

Before Submitting

Ensure tests pass:

make test-all
make check

Update documentation if needed
Add changelog entry if applicable

PR Requirements

[ ] All tests pass
[ ] Code follows style guidelines
[ ] Documentation updated
[ ] No security issues
[ ] Cross-provider tests pass (for provider changes)

PR Template

Use the provided PR template and fill out all relevant sections.

Release Process

Version Bumping

We use semantic versioning (MAJOR.MINOR.PATCH):

MAJOR: Breaking changes
MINOR: New features, backward compatible
PATCH: Bug fixes, backward compatible

Release Checklist

[ ] All tests pass
[ ] Documentation updated
[ ] Changelog updated
[ ] Version bumped in pyproject.toml
[ ] Release notes prepared

Creating a Release

Update version in pyproject.toml
Update changelog
Create release on GitHub
CI/CD will automatically publish to PyPI

Documentation

Documentation Structure

docs/
├── index.rst              # Main documentation page
├── installation.rst       # Installation guide
├── quickstart.rst         # Quick start guide
├── user_guide.rst         # Comprehensive user guide
├── api_reference.rst      # API documentation
├── providers.rst          # Provider documentation
├── cross_provider_testing.rst  # Cross-provider testing
├── examples.rst           # Examples and use cases
├── contributing.rst       # Contributing guide
└── changelog.rst          # Changelog

Building Documentation

# Build documentation
make docs

# Or manually
cd docs
make html

Documentation Guidelines

Use reStructuredText for documentation
Include code examples for all features
Update API docs when code changes
Test all examples before committing
Use consistent formatting

Getting Help

If you encounter issues during development:

Check the GitHub Issues
Review the troubleshooting section
Join our Discord community
Contact the development team at vcon@ietf.org

Recognition

Contributors will be recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation

Thank you for contributing to WTF Transcript Converter! 🎉