How to Contribute to PANORAMA 🤝#

Welcome! We’re thrilled that you’re interested in contributing to PANORAMA. Whether you’re fixing a typo, reporting a bug, or building a major new feature, your contribution matters, and we’re here to support you through the process.

This guide will walk you through basic ‘need to know’ to contribute effectively. More detailed information is available in the next pages.

Important

We encourage all contributions, this guide is not absolute rules but a help to go through. Start with what’s relevant to your contribution and refer back as needed.

Quick overview 🚀#

  1. Set up your development environment → See Development Setup

  2. Follow coding standards → See Development Methods

  3. Learn our git workflow → See Version Control Guide

  4. Write tests → See Testing Guidelines

  5. Update documentation → See Documentation Guide

  6. Submit your Pull Request → See Pull Request Process

Development Setup#

Clone the Repository#

# Clone your fork (after forking on GitHub)
git clone https://github.com/YOUR_USERNAME/PANORAMA.git
cd PANORAMA

# Add the upstream repository
git remote add upstream https://github.com/labgem/PANORAMA.git

Install in Development Mode#

# Install with all development tools
pip install -e .[dev,test,doc]

# Or install specific extras
pip install -e .[dev]   # Just development tools
pip install -e .[test]  # Just testing tools
pip install -e .[doc]   # Just documentation tools

Tip

The -e flag installs in “editable” mode, so your code changes take effect immediately!

Get Test Data#

# Clone the test data repository
git clone https://github.com/labgem/PANORAMA_test

# Set the environment variable
export PANORAMA_TEST_DATA_PATH=PANORAMA_test/

Our Development Workflow#

We use a structured workflow to keep the codebase stable and organized:

Branch Structure#

  • main - Stable, production-ready code

  • dev - Latest development version (your starting point!)

  • Feature branches - Your work happens here

Creating a Feature Branch#

# Start from dev
git checkout dev
git pull upstream dev

# Create your feature branch
git checkout -b feature/your-feature-name

Coding Standards 📝#

We follow consistent standards to keep the codebase maintainable:

  • Follow PEP 8 - Python’s official style guide

  • Use Ruff for formatting - Runs automatically, no debates!

  • Write docstrings - Document your functions and classes with the Google style

  • Use type hints - Helps catch bugs and improves readability

Tip

Most IDE have plugins to help you follow these standards.

Writing Tests 🧪#

Tests are crucial - they catch bugs and give everyone confidence that changes work correctly.

Running Tests#

# Run with coverage
pytest --cov=panorama  --test-data-path=test_data

More detail here

Test Types#

  • Unit tests - Test individual functions and classes in isolation

  • Functional tests - Test complete workflows and CLI commands

See our Testing Guidelines for comprehensive testing practices.

Updating Documentation 📚#

Documentation is just as important as code! When you make changes update

  • API documentation - Auto-generated from docstrings, but may need regeneration

  • User guides - If you add user-facing features

  • Developer docs - If you change development processes or architecture

To build the documentation locally:

cd docs
sphinx-autobuild source/ build/
# Open http://127.0.0.1:8000 in your browser

See our Documentation Building Guide for details.

Pull Request Process 🔄#

  1. Push your branch to your fork

  2. Create a Pull Request on GitHub targeting the dev branch

  3. Fill out the PR template with details about your changes

  4. Link related issues using “Fixes #123” or “Related to #456”

Note

VERSION will be updated by the maintainers when merging PRs. But you can also update it manually to make his life easier (he will appreciate it).

Tips and Tricks#

For more tips and tricks, see our Tips and Tricks page.

Getting Help 🆘#

Stuck on something? Here’s where you can find help:

  • GitHub Discussions - General questions and discussions

  • Issue tracker - Bug reports and feature requests

  • Pull Request comments - Questions about specific code

  • Tag maintainers - We’re here to help!

Remember: No question is too basic! We all started somewhere, and we want to support your contribution journey.

Recognition 🌟#

We value all contributions! Contributors are:

  • Listed in the project’s contributor list

  • Mentioned in release notes for significant contributions

  • Building their open source portfolio

Ready to Contribute? 🎉#

Pick an issue labeled good first issue or help wanted, or tackle something you’ve noticed that needs fixing. Don’t hesitate to ask questions - we’re here to help you succeed!

Thank you for contributing to PANORAMA. Your work helps advance bioinformatics research worldwide! 🚀