# 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](#development-setup)
2. **Follow coding standards** → See [Development Methods](devRules.md#dev-rules)
3. **Learn our git workflow** → See [Version Control Guide](git.md#git-guide)
4. **Write tests** → See [Testing Guidelines](unitTest.md#test-guide)
5. **Update documentation** → See [Documentation Guide](buildDoc.md#build-doc)
6. **Submit your Pull Request** → See [Pull Request Process](#pr-process)

## Development Setup

### Clone the Repository

```shell
# 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

```shell
# 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

```shell
# 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

```shell
# 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

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

```

More detail [here](unitTest.md#run-tests)

### Test Types

- **Unit tests** - Test individual functions and classes in isolation
- **Functional tests** - Test complete workflows and CLI commands

See our [Testing Guidelines](unitTest.md#test-guide) 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:

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

See our [Documentation Building Guide](buildDoc.md#build-doc) for details.

(pr-process)=

## 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](tipsandtricks.md) 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! 🚀