Contributing to BioMapper

Thank you for your interest in contributing to BioMapper! This guide will help you get started.

Getting Started

Fork the Repository

# Fork on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/biomapper.git
cd biomapper
git remote add upstream https://github.com/arpanauts/biomapper.git

Set Up Development Environment

# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Install all dependencies including dev, docs, and api extras
poetry install --with dev,docs,api

# Activate the virtual environment
poetry shell

# Verify installation
poetry run biomapper --help

# Start the API server (optional)
cd biomapper-api && poetry run uvicorn app.main:app --reload --port 8000

Create Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Development Workflow

1. Write Tests First (TDD)

# tests/unit/test_new_feature.py
def test_new_feature():
    """Test the new feature."""
    result = new_feature(input_data)
    assert result == expected_output

2. Implement Feature

Follow existing code patterns
Add type hints
Include docstrings
Handle errors gracefully

3. Run Quality Checks

# Format code
poetry run ruff format .

# Fix linting issues
poetry run ruff check . --fix

# Type checking
poetry run mypy biomapper

# Run tests
poetry run pytest

# Or run all checks
make check

4. Update Documentation

Update relevant .rst files in docs/source/
Add docstrings to new functions/classes
Update README if needed

Code Standards

Python Style

Follow PEP 8
Use ruff for formatting and linting
Maximum line length: 120 characters (as configured in ruff)
Use descriptive variable names
Python 3.11+ features are encouraged

Type Hints

All functions must have type hints:

from typing import Dict, List, Optional, Any

def process_data(
    input_data: List[Dict[str, Any]],
    threshold: float = 0.8,
    output_key: Optional[str] = None
) -> Dict[str, Any]:
    """Process data with threshold filtering.

    Args:
        input_data: List of data items
        threshold: Filter threshold (0.0-1.0)
        output_key: Optional output key name

    Returns:
        Processed data dictionary
    """
    ...

Docstrings

Use Google-style docstrings:

def complex_function(param1: str, param2: int) -> bool:
    """
    Brief description of function.

    Longer description explaining the function's purpose,
    behavior, and any important details.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ValueError: When param1 is empty
        TypeError: When param2 is not positive

    Example:
        >>> complex_function("test", 42)
        True
    """

Error Handling

from biomapper.core.exceptions import ValidationError
import logging

logger = logging.getLogger(__name__)

try:
    result = risky_operation()
except ValidationError as e:
    logger.error(f"Validation failed: {e}")
    return ActionResult(success=False, message=str(e))
except Exception as e:
    logger.exception("Unexpected error")
    return ActionResult(success=False, message="Internal error")

Creating New Actions

See Creating New Actions for detailed guide. Quick checklist:

✅ Write tests first
✅ Inherit from TypedStrategyAction
✅ Use Pydantic for parameters
✅ Add @register_action decorator
✅ Handle errors gracefully
✅ Update context appropriately
✅ Add comprehensive docstrings
✅ Place in correct directory

Testing Requirements

Minimum 80% code coverage
All new features must have tests
Test edge cases and error conditions
Use pytest fixtures for common data
Mock external dependencies

# Run tests with coverage
poetry run pytest --cov=biomapper --cov-report=term-missing

Commit Guidelines

Commit Messages

Follow conventional commits:

feat: Add metabolite CTS bridge action

- Implement Chemical Translation Service integration
- Add retry logic for API calls
- Include comprehensive error handling

Closes #123

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes
refactor: Code refactoring
test: Test additions/changes
chore: Maintenance tasks

Pull Request Process

Update Your Branch

git fetch upstream
git rebase upstream/main

Create Pull Request
- Use descriptive title
- Reference related issues
- Include test results
- Add screenshots if UI changes

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All checks passing

Address Review Comments
- Respond to all comments
- Make requested changes
- Re-request review when ready

Documentation

Building Docs

cd docs
poetry run make html
open build/html/index.html

Writing Docs

Use reStructuredText (.rst) format
Include code examples
Add cross-references
Keep it concise and clear

Project Structure

Understanding the Layout

biomapper/
├── src/                     # Source code root
│   ├── actions/             # Strategy actions
│   ├── api/                 # FastAPI components
│   ├── cli/                 # CLI interface
│   ├── client/              # Python client
│   ├── configs/             # YAML strategies
│   ├── core/                # Core library
│   └── integrations/        # External integrations
├── tests/                   # Test suite
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   └── performance/         # Performance tests
├── docs/                    # Documentation
└── scripts/                 # Development scripts

Where to Add Code

New actions: src/actions/entities/ (organized by entity type)
API endpoints: src/api/routes/
Client methods: src/client/client_v2.py
Tests: tests/unit/ or tests/integration/
Strategies: src/configs/strategies/

Getting Help

Issues: Check existing issues or create new ones
Discussions: Use GitHub Discussions for questions
Documentation: Read CLAUDE.md for AI assistance
Discord: Join our community (if available)

Code of Conduct

Be respectful and inclusive
Welcome newcomers
Give constructive feedback
Focus on what’s best for the community
Show empathy towards others

License

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

Recognition

Contributors are recognized in:

GitHub contributors page
CONTRIBUTORS.md file
Release notes

Thank You!

Your contributions make BioMapper better for everyone. We appreciate your time and effort!

—

Verification Sources

Last verified: 2025-08-17

This documentation was verified against the following project resources:

/biomapper/README.md (installation instructions and project overview)
/biomapper/CLAUDE.md (development commands and updated project structure)
/biomapper/pyproject.toml (Poetry dependency management and Python 3.11+ requirement)
/biomapper/src/biomapper/actions/typed_base.py (TypedStrategyAction pattern for new actions)
/biomapper/src/biomapper/actions/registry.py (self-registering action system)
/biomapper/src/biomapper/ (current project structure under src/ directory)