Contributing¶

Contributions are welcome! This project is in early development, and we're building the foundation for production ML explainability monitoring.

How to Contribute¶

Report Issues¶

Found a bug or have a feature request? Open an issue on GitHub.

Submit Pull Requests¶

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Make your changes with tests
Ensure code passes all checks
Submit a pull request

Development Setup¶

Prerequisites¶

Python 3.11 or higher
Poetry for dependency management
Git

Setup Steps¶

# Clone your fork
git clone https://github.com/YOUR-USERNAME/shap-monitor.git
cd shap-monitor

# Install dependencies
poetry install --with dev --with docs

# Install pre-commit hooks
poetry run pre-commit install

Development Workflow¶

Running Tests¶

# Run all tests
make test

# Run with coverage
make coverage

# Run specific test file
poetry run pytest tests/test_monitor.py

# Run specific test
poetry run pytest tests/test_monitor.py::test_monitor_initialization

Code Formatting & Linting¶

The project uses Black and Ruff for code formatting and linting.

# Format all code
make lint

Pre-commit Hooks¶

Pre-commit hooks automatically run checks before commits:

# Manually run all hooks
poetry run pre-commit run --all-files

Code Guidelines¶

Style Guide¶

Follow PEP 8 style guide
Use Black for formatting (line length: 100)
Use type hints for all function signatures
Write docstrings for public APIs (NumPy style)

Documentation¶

Add docstrings to all public classes and methods
Use NumPy-style docstrings
Include examples in docstrings where helpful
Update user guide for new features

Example docstring:

def summary(self, start_dt: datetime, end_dt: datetime) -> pd.DataFrame:
    """Compute summary statistics for SHAP values in a date range.

    Parameters
    ----------
    start_dt : datetime
        Start of the date range (inclusive).
    end_dt : datetime
        End of the date range (inclusive).

    Returns
    -------
    DataFrame
        Summary statistics indexed by feature name.

    Examples
    --------
    >>> analyzer = SHAPAnalyzer(backend)
    >>> summary = analyzer.summary(start_date, end_date)
    >>> print(summary['mean_abs'].head())
    """

Testing¶

Write tests for new features
Maintain or improve code coverage
Use pytest fixtures for common setups
Test edge cases and error conditions

Example test:

def test_monitor_log_batch(tmp_path):
    """Test SHAPMonitor.log_batch() logs data correctly."""
    # Setup
    explainer = create_test_explainer()
    monitor = SHAPMonitor(
        explainer=explainer,
        data_dir=tmp_path,
        sample_rate=1.0
    )

    # Execute
    X = create_test_data()
    monitor.log_batch(X)

    # Verify
    backend = ParquetBackend(tmp_path)
    df = backend.read(datetime.now(), datetime.now())
    assert len(df) > 0

Pull Request Guidelines¶

Before Submitting¶

Tests pass (make test)
Code is formatted (make lint)
Documentation is updated
Commit messages are clear and descriptive

PR Description¶

Include:

Summary of changes
Motivation and context
Related issues (if any)
Testing done
Screenshots (if applicable)

Review Process¶

Automated checks must pass
At least one maintainer review required
Address feedback
Maintain clean commit history

Documentation¶

Building Documentation¶

# Serve documentation locally
make docs-serve

# Build documentation
make docs-build

# Deploy to GitHub Pages (maintainers only)
poetry run mkdocs gh-deploy

Writing Documentation¶

Write clear, concise documentation
Include code examples
Update relevant sections when adding features
Check for broken links

Release Process¶

(For maintainers)

Update version in pyproject.toml
Update CHANGELOG.md
Create release tag
Build and publish to PyPI
Update documentation

Code of Conduct¶

Be respectful and inclusive
Focus on constructive feedback
Help newcomers get started
Follow GitHub's Community Guidelines

Questions?¶

Ask in an Issue
Check existing documentation

License¶

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