Skip to content

Contributing

Thank you for your interest in contributing to gbcms!

Full Guide

See the main contributing guide for complete details.

Contributing to gbcms

Thank you for your interest in contributing to GetBaseCounts! This document provides guidelines and instructions for contributing.

Development Setup

  1. Clone the repository 

    git clone https://github.com/msk-access/gbcms.git
cd gbcms

  2. Install uv (if not already installed) 

    curl -LsSf https://astral.sh/uv/install.sh | sh

  3. Install development dependencies 

    # Install Rust (if not installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build and install in development mode
pip install maturin
maturin develop --release

Development Workflow

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=gbcms --cov-report=html

# Run specific test file
pytest tests/test_accuracy.py

# Run with verbose output
pytest -v

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Fix linting issues automatically
ruff check --fix src/ tests/

# Type checking
mypy src/

Building and Testing Docker

# Build Docker image
docker build -t gbcms:latest .

Code Style

  • Follow PEP 8 style guidelines
  • Use type hints for all function signatures
  • Write docstrings for all public functions and classes
  • Keep functions focused and single-purpose
  • Maximum line length: 100 characters

Testing Guidelines

  • Write tests for all new features
  • Maintain or improve code coverage
  • Use descriptive test names
  • Use fixtures for common test setup
  • Test edge cases and error conditions

Counting Engine Changes

Changes to rust/src/counting.rs require additional verification:

  • Unit tests: cargo test must pass (all existing tests + new tests for the change)
  • 22-BAM regression: Run the regression suite and verify no unintended count shifts
  • Variant-type coverage: If modifying a specific variant type (SNP/MNP/Indel/Complex), ensure the regression MAF includes representative variants of that type
  • MnpResult paths: Any changes to MNP handling must test all 5 MnpResult variants: Ref, Alt, LowQuality, ThirdAllele, Structural

Pull Request Process

  1. Create a feature branch 

    git checkout -b feature/your-feature-name

  2. Make your changes

  3. Write code following the style guidelines
  4. Add tests for new functionality

  5. Update documentation as needed

  6. Run tests and linters 

    make test
make lint

  7. Commit your changes 

    git add .
git commit -m "Description of your changes"

  8. Push to your fork 

    git push origin feature/your-feature-name

  9. Create a Pull Request

  10. Provide a clear description of the changes
  11. Reference any related issues
  12. Ensure all CI checks pass

Reporting Issues

When reporting issues, please include:

  • Python version
  • Operating system
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Error messages or logs

Feature Requests

We welcome feature requests! Please:

  • Check if the feature already exists
  • Provide a clear use case
  • Describe the expected behavior
  • Consider submitting a PR if you can implement it

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback
  • Help others learn and grow

Questions?

Feel free to open an issue for questions or reach out to the maintainers.

Thank you for contributing!