Skip to content

Contributing to py-gbcms

Thank you for your interest in contributing to py-gbcms! This guide covers both code contributions and documentation updates.

Table of Contents

Code Contributions

Development Setup

  1. Clone the repository 

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

  2. Install uv (if not already installed) 

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

  3. Install development dependencies 

    uv pip install -e ".[dev]"

Development Workflow

Running Tests

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_counter.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

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

Documentation Contributions

Local Preview

Preview documentation locally while editing:

# Install MkDocs (first time only)
pip install mkdocs-material

# Serve docs with live reload
mkdocs serve

Then open http://127.0.0.1:8000 in your browser. Changes to docs/ files will auto-refresh.

Documentation URLs

  • Production (from main): https://msk-access.github.io/py-gbcms/
  • Staging (from develop): https://msk-access.github.io/py-gbcms/gh-pages-staging/
  • GitBook: https://cmo-ci.gitbook.io/py-gbcms/

Git-Flow Documentation Workflow

# 1. Work on feature branch
git checkout -b feature/update-docs

# 2. Edit docs and preview locally
mkdocs serve

# 3. Push to develop
git push origin feature/update-docs
# Create PR to develop

# 4. Merge to develop
# → Auto-deploys to staging URL

# 5. Release: merge develop → main  
# → Auto-deploys to production GitHub Pages

Building Docs Manually

# Build static site
mkdocs build
# Output in site/ directory

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

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!