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
   
   # A virtual environment: the build below installs into one, and the system
   # pip is often externally managed.
   python3 -m venv .venv
   source .venv/bin/activate
   
   # Build and install in development mode. Needs pip>=25.1 (or `maturin develop --uv`):
   # it also installs the `dev` dependency group (PEP 735).
   pip install --upgrade "pip>=25.1" 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 .

Public API vs internals

gbcms._rs is the internal PyO3 extension module. It is underscore-prefixed and absent from gbcms.__all__ on purpose: its surface (an ~88-field BaseCounts, a ~35-parameter count_bam_binned) tracks the engine and changes with it. It is not covered by Semantic Versioning — do not depend on it from outside this repository.

The supported API is what gbcms.__all__ exports: Pipeline, the config models, Variant, merge_mafs, and observe_molecules. A new engine capability that external consumers need should get a narrow public wrapper (see src/gbcms/observations.py) rather than exposing _rs — that way the promise we keep stable is small enough to actually honour.

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 the counting engine (rust/src/counting/ — especially engine.rs and variant_checks.rs) require additional verification:

• Unit tests: cargo test must pass (all existing tests + new tests for the change)
• BAM-slice regression: Run the BAM-slice regression suite and verify no unintended count shifts (see the developer guide for the current slice set)
• Binning invariance: counts must not depend on bin geometry; the binning-invariance tests and count_checked compare every field (see .agents/rules/architecture.md)
• Read census: pure-indel counting is checked against tests/census.py; a change that moves the census property test needs a decision, not a new expectation
• 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 — the Python and Rust gates (make test/make lint cover Python only; the Rust lint/tests must be run separately, or you'll ship un-linted Rust):

   make test && make lint                                   # Python: pytest + ruff/black/mypy
   cd rust && cargo clippy --all-targets -- -D warnings && cargo test && cd ..
   

   The load-bearing invariants (binning invariance, one base-quality gate across alignment backends, the 4 counting-test invariants) are in .agents/rules/architecture.md (in the repo root) — read them before touching the engine.

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!