contributing.md

Contributing to embpy

Thank you for your interest in contributing to embpy! This guide outlines our local development workflows, branch conventions, and continuous integration testing matrices.

---

Local Development Workflow

1. Clone & Set Up Tracking

Clone the repository:

git clone https://github.com/theislab/embpy.git
cd embpy

2. Environment Setup

We recommend setting up an isolated virtual environment:

# Using Python venv
python -m venv .venv
source .venv/bin/activate  # On Windows PowerShell: .venv\Scripts\Activate.ps1

# Install in editable mode with development, testing, and model extras
pip install -e ".[models,test,dev]"

---

Branch Conventions

Branch Pattern	Purpose
main	Primary branch for active development, releases, and documentation.
feat/<name>	New features, model wrappers, or substantial additions.
fix/<name>	Bug fixes and compatibility adjustments.
docs/<name>	Documentation updates and guides.

Please ensure all new feature branches branch from and target main.

---

Running Tests

We use pytest for automated testing:

# Run the core test suite
python -m pytest tests/ -v

# Run tests for a specific modality
python -m pytest tests/ -k "protein"

---

CI Testing Matrices

Our GitHub Actions automatically run the test suite against a multi-dimensional matrix on every pull request:

Dimension	Scope
Operating Systems	Ubuntu 22.04 (Linux), macOS (Latest), Windows Server 2022
Python Versions	3.11, 3.12, 3.13
Execution Targets	CPU Runners (Pull Requests), GPU Self-Hosted Runners (Releases)
Packaging Modes	Pure pip core, [models] extras, [all] extras

Before opening a pull request, ensure that:

1. Code adheres to formatting rules (ruff check . and ruff format .).
2. Windows multiprocessing safety is maintained (if __name__ == '__main__': guards where appropriate).
3. Heavy dependencies remain in optional extras rather than the core package.