Contributing¶

We welcome contributions to CDL Convert! Whether you’re fixing bugs, adding features, improving documentation, or submitting sample files, your help is appreciated.

Contributing CDL and EDL Samples¶

Please, please, please submit samples of the following formats:

FLEx
CCC
CDL

These are complex formats, and seeing real-world samples helps write tests that ensure correct parsing of real-world EDLs and CDLs. If you don’t see a CDL format listed that you know exists, open an issue asking for parse/write support for the format, and include a sample.

Issues & Bugs¶

Take a look at the issues page and if you see something you think you can tackle, leave a comment saying you’re going to work on it. While many issues are already assigned to the principal authors, just because it’s assigned doesn’t mean work has begun.

Feel welcome to post:

Bug reports
Feature requests
Questions about behavior
Documentation improvements

Development Workflow¶

Setting Up Your Development Environment¶

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/cdl_convert.git
cd cdl_convert

Create a virtual environment:

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

Install in development mode with Hatch for running tools:
```
pip install hatch
pip install -e .[dev]
```

Create a feature branch:

git checkout develop
git checkout -b feature/your-feature-name

Making Changes¶

Branch naming conventions:

feature/ - New features
bugfix/ - Bug fixes
docs/ - Documentation improvements
test/ - Test additions or improvements

Submitting Your Changes¶

Push your feature branch to GitHub:

git push origin feature/your-feature-name

Create a pull request from your feature branch to the develop branch of the main repository
Link to related issues in your pull request description using Fixes #123 or Relates to #456

Pull Request Guidelines¶

CDL Convert needs your collaboration, but we only have limited time to review and merge contributions. Following these guidelines will ensure your pull request is accepted and integrated quickly.

Run the Tests!¶

Before you submit a pull request, please run the entire test suite and code quality checks:

# Run tests with coverage
hatch run test:cov

# Run linting
hatch run lint

# Run type checking
hatch run type-check

# Format code
hatch run format

If the tests are failing, it’s likely that you accidentally broke something. Note which tests are failing and how your code might have affected them. If your change is intentional (for example, you changed behavior), adjust the test suite to match, get it back into a passing state, and then submit it.

If your code fails the tests, it will be rejected. GitHub Actions checks all pull requests automatically.

Testing Across Python Versions¶

To test across all supported Python versions (3.11-3.14):

hatch run test:all

This uses Hatch’s matrix testing to run tests in Python 3.11, 3.12, 3.13, and 3.14.

Writing Tests¶

If your pull request adds a feature but lacks tests, it will be rejected.

Older tests are written using the standard unittest framework, but new tests can be written using pytest and I’ll try and keep up. Please keep test cases as simple as possible while maintaining good coverage of the code you added.

Example test structure:

def test_my_new_feature():
    """Test that my new feature works correctly."""
    # Arrange
    input_data = create_test_data()
    
    # Act
    result = my_new_feature(input_data)
    
    # Assert
    assert result.expected_value == "expected"

Test files should be in the tests/ directory
Name test files test_*.py
Name test functions test_*
Use descriptive test names that explain what is being tested
Include docstrings in test functions
Use fixtures for common test data

Documentation Contributions¶

Documentation is just as important as code! We use Sphinx with MyST Parser for documentation, which means you can write in Markdown.

Writing Documentation¶

Documentation files are in cdl_convert/docs/
Use Markdown (.md) for new documentation
Follow MyST syntax for directives and cross-references

Building Documentation Locally¶

Using Hatch (recommended):

# Build documentation
hatch run docs:build

# Clean and rebuild
hatch run docs:rebuild

# Serve documentation locally (opens on http://localhost:8000)
hatch run docs:serve

# Check for broken links
hatch run docs:linkcheck

Or manually:

cd cdl_convert/docs
pip install -r requirements.txt
python -m sphinx -b html . _build/html

Then open _build/html/index.html in your browser.

Documentation Style Guide¶

Use clear, concise language
Include code examples where appropriate
Add cross-references to related classes and functions
Test that all cross-references resolve correctly
Verify documentation renders correctly on GitHub

Code Style Guidelines¶

If the code style doesn’t follow PEP-8, it will be rejected.

Use Hatch to check and format your code:

# Check code style
hatch run lint

# Auto-format code
hatch run format

# Run type checking
hatch run type-check

Python Version¶

CDL Convert supports Python 3.11-3.14. Write code that works across these versions.

Development Workflow with Hatch¶

CDL Convert uses Hatch for modern Python project management. Hatch provides isolated environments for testing, linting, and documentation building.

Available Hatch commands:

# Testing
hatch run test              # Run tests in current Python version
hatch run test:all          # Run tests across all Python versions (3.11-3.14)
hatch run test:cov          # Run tests with coverage report

# Code Quality
hatch run lint              # Check code style with ruff
hatch run format            # Auto-format code with ruff
hatch run type-check        # Run mypy type checking
hatch run security:scan     # Run security checks with bandit

# Documentation
hatch run docs:build        # Build documentation
hatch run docs:rebuild      # Clean and rebuild documentation
hatch run docs:serve        # Serve documentation locally
hatch run docs:linkcheck    # Check for broken links

You don’t need to activate a virtual environment when using Hatch - it manages environments automatically!

Type Hints¶

Use type hints for function signatures:

def parse_file(input_file: str) -> ColorCorrection | ColorCollection:
    """Parse a CDL file and return the appropriate object."""
    ...

Docstrings¶

Use Google-style docstrings:

def my_function(param1: str, param2: int) -> bool:
    """Brief description of function.
    
    Longer description if needed.
    
    Args:
        param1: Description of param1
        param2: Description of param2
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When param1 is invalid
    """
    ...

Imports¶

Organize imports in this order:

Standard library imports
Third-party imports
Local application imports

import os
from pathlib import Path

import opentimelineio as otio

from cdl_convert.base import AscColorSpaceBase
from cdl_convert.correction import ColorCorrection

Copyright of Submitted Contributions¶

When submitting, you’ll be asked to waive copyright to your submitted code to the listed authors. This is so we can keep a handle on the code and change the license for future releases if needed.

Getting Help¶

If you have questions about contributing:

Check the Frequently Asked Questions for common questions
Open a GitHub Discussion
Ask in your pull request or issue

Code of Conduct¶

Be respectful and constructive in all interactions. We’re all here to make CDL Convert better!

Thank You!¶

Your contributions make CDL Convert better for everyone. Thank you for taking the time to contribute!