Contributing to VariantCentrifuge¶

We welcome contributions to VariantCentrifuge! This document provides guidelines for contributing to the project.

Getting Started¶

Prerequisites¶

Before contributing, ensure you have:

Python 3.7+ installed
Git configured with your GitHub account
External bioinformatics tools (bcftools, snpEff, SnpSift, bedtools) installed
Familiarity with the VariantCentrifuge codebase and documentation

Development Setup¶

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/variantcentrifuge.git
cd variantcentrifuge

Add upstream remote:

git remote add upstream https://github.com/scholl-lab/variantcentrifuge.git

Set up development environment:

mamba env create -f conda/environment.yml
mamba activate annotation
pip install -e .
pre-commit install

Ways to Contribute¶

Reporting Bugs¶

When reporting bugs, please include:

Clear description of the problem
Steps to reproduce the issue
Expected vs actual behavior
Environment details (OS, Python version, tool versions)
Log output or error messages
Example data if possible (anonymized)

Use the bug report template on GitHub.

Suggesting Features¶

For feature requests, please provide:

Clear description of the proposed feature
Use case and motivation
Proposed implementation (if you have ideas)
Examples of how it would be used

Use the feature request template on GitHub.

Contributing Code¶

Types of Contributions¶

Bug fixes - Fix identified issues
New features - Add functionality
Performance improvements - Optimize existing code
Documentation - Improve or expand documentation
Tests - Add or improve test coverage
Refactoring - Improve code structure without changing functionality

Development Workflow¶

Create an issue for significant changes (optional for small fixes)

Create a feature branch:

git checkout -b feature/descriptive-name

Make your changes following the coding standards
Add tests for new functionality
Update documentation as needed
Run the test suite:
```
pytest
black .
isort .
flake8 .
```
Commit your changes with clear messages
Push to your fork and create a pull request

Code Standards¶

Follow PEP 8 with 100-character line length
Use type hints for function signatures
Write docstrings in Google format for all public functions
Add unit tests for new functionality
Keep functions focused and modular
Use meaningful variable names
Handle errors gracefully with appropriate logging

Testing Guidelines¶

Write tests for all new code
Ensure tests pass before submitting PR
Use pytest fixtures for setup/teardown
Mock external dependencies (files, external tools)
Test both success and failure cases
Aim for high test coverage

Example test:

def test_extract_variants_success(mock_run_command):
    """Test successful variant extraction."""
    # Arrange
    mock_run_command.return_value = CompletedProcess(
        args=[], returncode=0, stdout="Success"
    )
    
    # Act
    result = extract_variants("input.vcf", "output.vcf", "chr1:1000-2000")
    
    # Assert
    assert result == "output.vcf"
    mock_run_command.assert_called_once()

Documentation Guidelines¶

Update user documentation for new features
Add docstrings to all new functions and classes
Include code examples in docstrings where helpful
Update API documentation automatically via docstrings
Test documentation builds locally before submitting

Example docstring:

def filter_variants(vcf_file: str, filter_expr: str, output_file: str) -> str:
    """Filter variants using SnpSift filter expression.
    
    Args:
        vcf_file: Path to input VCF file
        filter_expr: SnpSift filter expression
        output_file: Path to output filtered VCF file
        
    Returns:
        Path to the filtered output file
        
    Raises:
        FileNotFoundError: If input VCF file doesn't exist
        RuntimeError: If SnpSift command fails
        
    Example:
        >>> filter_variants("input.vcf", "QUAL >= 30", "filtered.vcf")
        "filtered.vcf"
    """

Pull Request Process¶

Before Submitting¶

Code follows project style guidelines
Tests pass locally (pytest)
Code is properly formatted (black . and isort .)
Linting passes (flake8 .)
Documentation builds successfully
Commit messages are clear and descriptive
Changes are focused and atomic

Pull Request Template¶

When creating a pull request, include:

Description of changes made
Motivation for the changes
Testing performed
Breaking changes (if any)
Related issues (use “Fixes #123” format)

Review Process¶

Automated checks run on all PRs (CI/CD)
Code review by maintainers
Discussion and iteration if needed
Approval and merge by maintainers

After Submission¶

Respond to feedback promptly
Make requested changes in the same branch
Keep the PR up to date with main branch if needed
Participate in discussions constructively

Community Guidelines¶

Code of Conduct¶

We are committed to fostering an inclusive and welcoming community. Please:

Be respectful and considerate
Welcome newcomers and help them get started
Focus on what’s best for the community
Show empathy towards other community members
Be collaborative and constructive in discussions

Communication¶

GitHub Issues - Bug reports, feature requests, and project discussions
GitHub Discussions - General questions and community discussions
Pull Request Comments - Code-specific discussions
Email - Contact maintainers for sensitive issues

Recognition¶

Contributors are recognized through:

Git commit history - Your contributions are permanently recorded
Changelog entries - Significant contributions noted in releases
Contributors file - Recognition of ongoing contributors
GitHub contributors graph - Visual representation of contributions

Getting Help¶

For Contributors¶

Read the documentation thoroughly before asking questions
Search existing issues to see if your question has been answered
Check the development guide for technical details
Ask specific questions with context and examples

For Maintainers¶

If you become a regular contributor, you may be invited to join the maintainer team. Maintainer responsibilities include:

Reviewing pull requests thoroughly and constructively
Triaging issues and labeling them appropriately
Helping newcomers get started with contributing
Making decisions about project direction and priorities
Maintaining code quality and project standards

Thank You!¶

Thank you for considering contributing to VariantCentrifuge! Your contributions help make this tool better for the entire genomics community.

Whether you’re fixing a typo, adding a feature, or improving documentation, every contribution is valuable and appreciated.