Contributing

We welcome contributions to the DDI Toolkit! This document outlines how to contribute to the project.

Getting Started

Fork the repository on GitHub
Clone your fork locally
Create a new branch for your feature or bug fix
Make your changes
Run tests to ensure everything works
Submit a pull request

Development Setup

# Fork and clone the repository
git clone https://github.com/yourusername/ddi-toolkit.git
cd ddi-toolkit

# Option 1: Using uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -e .[dev]

# Option 2: Using standard pip
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .[dev]

# Verify installation
pytest

Running Tests

# Run all tests
pytest

# Run tests with verbose output
pytest -v

# Run specific test file
pytest tests/test_ddicodebook.py

# Run tests for specific module
pytest tests/test_ddicdi_specification.py

Code Style

Follow PEP 8 guidelines and use meaningful names:

# Good
def load_ddi_codebook(file_path: str) -> codeBookType:
    """Load a DDI-Codebook from XML file."""
    return ddicodebook.loadxml(file_path)

# Use type hints
from typing import Optional, List, Dict

def extract_variables(codebook: codeBookType,
                     var_type: Optional[str] = None) -> List[Dict]:
    """Extract variable information from codebook."""
    # Implementation here
    pass

Documentation

Documentation is built with Sphinx:

# Build documentation
cd docs
make html

# View documentation
open build/html/index.html

Submitting Changes

Ensure all tests pass
Update documentation if needed
Add or update tests for new features
Follow the existing code style
Write clear commit messages
Submit a pull request with a clear description

Types of Contributions

High Priority:

DDI-CDI specification coverage improvements
Test coverage enhancements
Documentation updates and examples
Bug fixes in DDI-Codebook processing

Medium Priority:

Performance optimizations
Additional utility functions
Integration improvements
Error handling enhancements

Experimental:

DDI-Codebook to DDI-CDI conversion
Advanced RDF serialization features
Integration with external tools

Guidelines

Code Quality:

Keep changes focused and atomic
Include tests for new functionality
Update documentation for user-facing changes
Follow Python naming conventions (except DDI-CDI classes)
Add comprehensive type hints
Write clear docstrings with examples

Testing:

Write unit tests for all new functions
Test edge cases and error conditions
Ensure existing tests continue to pass
Use meaningful test names and assertions

Documentation:

Update API documentation for new features
Add examples to demonstrate usage
Update changelog for significant changes
Keep README current with new capabilities

DDI-Specific Guidelines:

Maintain compatibility with DDI specifications
Handle malformed XML gracefully in DDI-Codebook
Follow DDI-CDI naming conventions for model classes
Test with real-world DDI documents when possible