Contributor Guide

Thank you for your interest in contributing to IDTrack! This project is open-source under the BSD 3-Clause License and welcomes contributions from the community.

Ways to Contribute

There are many ways to contribute to IDTrack, regardless of your experience level:

Contribution Type	Description
Report Bugs	Help us identify issues and improve reliability
Request Features	Suggest new functionality or enhancements
Improve Documentation	Fix typos, clarify explanations, add examples
Submit Code	Fix bugs or implement new features
Add Organism Support	Configure external databases for new species
Answer Questions	Help other users in discussions and issues

Quick Links

Source Code	github.com/theislab/idtrack
Documentation	idtrack.readthedocs.io
Issue Tracker	GitHub Issues
Pull Requests	GitHub Pull Requests
Discussions	GitHub Discussions
Code of Conduct	Contributor Covenant Code of Conduct

Reporting Bugs

Found a bug? Please report it on the Issue Tracker.

A good bug report includes:

Summary - A clear, concise description of the problem
Environment - Python version, IDTrack version, operating system
Steps to reproduce - Minimal code example that triggers the bug
Expected behavior - What you expected to happen
Actual behavior - What actually happened (include error messages)

Bug Report Template

## Environment
- IDTrack version: 0.0.x (run `python -c "import idtrack; print(idtrack.__version__)"`)
- Python version: 3.11.x (run `python --version`)
- OS: Ubuntu 22.04 / macOS 14.x / Windows 11

## Description
A clear, concise description of what the bug is.

## Steps to Reproduce
```python
import idtrack

# Minimal code that triggers the bug
api = idtrack.API(local_repository="./cache")
# ...
```

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened. Include the complete error traceback if applicable.

## Additional Context
Any other context about the problem (screenshots, related issues, etc.).

Requesting Features

Have an idea for a new feature? Open an issue on the Issue Tracker with:

Use case - Describe the problem you’re trying to solve
Proposed solution - Your suggested approach
Alternatives considered - Other approaches you’ve thought about
Impact - Who would benefit from this feature

Tip

It’s a good idea to open an issue before starting work on a feature. This allows maintainers to discuss the approach and avoid duplicate effort.

Development Setup

Prerequisites

Before setting up your development environment, ensure you have:

Requirement	Details
Python	3.9 or later (3.11 recommended)
Git	For version control
Pandoc	Required for building documentation with Jupyter notebooks

Install Pandoc:

# macOS
$ brew install pandoc

# Ubuntu/Debian
$ sudo apt-get install -y pandoc

# Windows (using Chocolatey)
$ choco install pandoc

# Or download from https://pandoc.org/installing.html

Development Tools

IDTrack uses the following tools for development:

Tool	Purpose	Installation
Poetry	Dependency management	`pip install poetry`
Nox	Test automation	`pip install nox`
nox-poetry	Nox + Poetry integration	`pip install nox-poetry`

Install all development tools:

$ pip install poetry poetry-plugin-export nox nox-poetry

# Alternative: If you installed Poetry via pipx
$ pipx install poetry
$ pipx inject poetry poetry-plugin-export

Setting Up the Project

Step 1: Fork and clone

# Fork on GitHub, then clone your fork
$ git clone https://github.com/YOUR_USERNAME/idtrack.git
$ cd idtrack
$ git remote add upstream https://github.com/theislab/idtrack.git

Step 2: Install dependencies with Poetry

$ make install

This installs IDTrack in development mode with all dependencies.

Step 3: Verify your setup

# Start an interactive Python session
$ poetry run python

# Or run the CLI
$ poetry run idtrack --help

Step 4: Install pre-commit hooks (recommended)

$ nox --session=pre-commit -- install

This automatically runs code formatting and linting checks before each commit.

Note

See Installation for additional requirements like HDF5 on Apple Silicon.

Running Tests

IDTrack uses pytest for testing and Nox for test automation.

Run the Full Test Suite

$ nox

This runs all tests, linting, and type checking.

Run Specific Test Sessions

List available sessions:

$ nox --list-sessions

Run only unit tests:

$ nox --session=tests

Run tests with a specific Python version:

$ nox --session=tests --python=3.11

Run Tests Directly with pytest

For faster iteration during development:

# Run all tests
$ poetry run pytest

# Run a specific test file
$ poetry run pytest tests/test_api.py

# Run tests matching a pattern
$ poetry run pytest -k "test_convert"

# Run with verbose output
$ poetry run pytest -v

# Run with coverage report
$ poetry run pytest --cov=idtrack --cov-report=html

Test Organization

Tests are located in the tests/ directory:

tests/
├── test_api.py           # Public API tests
├── test_graph.py         # Graph engine tests
├── test_harmonize.py     # Harmonization tests
├── conftest.py           # Shared fixtures
└── ...

Building Documentation

IDTrack uses Sphinx with nbsphinx to build documentation from reStructuredText files and Jupyter notebooks.

Install Documentation Dependencies

$ pip install -r docs/requirements.txt

Build the Documentation

$ cd docs
$ make html

The generated HTML files are in docs/_build/html/. Open index.html in your browser.

Live Preview During Editing

For automatic rebuilds while editing:

$ pip install sphinx-autobuild
$ cd docs
$ sphinx-autobuild . _build/html

Then open http://localhost:8000 in your browser.

Note

IDTrack itself must be installed for the API documentation to build correctly. Notebooks are not executed during builds (nbsphinx_execute = "never"); they are rendered with pre-existing outputs.

Documentation Guidelines

When contributing to the documentation website:

Keep pages scannable: start with a short summary, then use .. contents:: and tables for structured material.
Prefer cross-links over duplication: use :doc:`...` for pages and :meth:`...` / :class:`...` for API items.
Tutorial notebooks are source of truth for narrative workflows: notebooks live in docs/_notebooks and are rendered by nbsphinx without execution during builds.
Avoid huge notebook outputs: keep outputs concise and deterministic so the rendered docs remain readable.

Submitting Changes

Workflow Overview

Step	Action	Details
1	Fork & Clone	Create your own copy of the repository
2	Branch	Create a feature branch from `development`
3	Develop	Make your changes with tests
4	Test	Run tests and linting locally
5	Submit	Create a pull request

Step-by-Step Guide

Step 1: Fork and clone

# Fork on GitHub, then clone your fork
$ git clone https://github.com/YOUR_USERNAME/idtrack.git
$ cd idtrack
$ git remote add upstream https://github.com/theislab/idtrack.git

Step 2: Create a feature branch

$ git checkout development
$ git pull upstream development
$ git checkout -b feature/your-feature-name

Use descriptive branch names:

feature/add-zebrafish-support
fix/hgnc-download-timeout
docs/improve-quickstart

Step 3: Make your changes

Write clear, focused commits
Follow the existing code style
Add tests for new functionality
Update documentation if needed

Step 4: Run tests and linting

$ nox

All tests and checks must pass before submitting.

Step 5: Push and create a pull request

$ git push origin feature/your-feature-name

Then open a pull request on GitHub against the development branch.

Pull Request Guidelines

Your pull request should:

Pass all tests - The Nox test suite must pass without errors
Include tests - Add tests for bug fixes and new features
Update documentation - If your changes affect user-facing behavior
Have a clear description - Explain what the PR does and why
Reference issues - Link to related issues (e.g., “Fixes #123”)

Pull Request Template

## Summary
Brief description of what this PR does.

## Changes
- Added support for X
- Fixed bug in Y
- Updated documentation for Z

## Testing
- [ ] Unit tests added/updated
- [ ] All tests pass locally (`nox`)
- [ ] Documentation builds without errors

## Related Issues
Fixes #123

Code Style

IDTrack follows these conventions:

Aspect	Convention
Formatting	Black (automatically applied by pre-commit)
Linting	Ruff
Type hints	Use type annotations for public APIs
Docstrings	NumPy style

Example Function

def convert_identifier(
    self,
    identifier: str,
    to_release: int,
    explain: bool = False,
) -> ConversionResult:
    """Convert a biological identifier to a target release.

    Parameters
    ----------
    identifier
        The identifier to convert (e.g., gene symbol, Ensembl ID).
    to_release
        Target Ensembl release number.
    explain
        If True, include detailed mapping information.

    Returns
    -------
    ConversionResult
        The conversion result with mapped identifiers.

    Raises
    ------
    ValueError
        If the identifier format is not recognized.

    Examples
    --------
    >>> api.convert_identifier("TP53", to_release=112)
    ConversionResult(...)
    """
    ...

Adding Organism Support

Want to add support for a new organism? This involves configuring external databases for the species.

See the detailed tutorial: Part 2 — External Database Configuration

The general process is:

Create a YAML configuration for external databases
Test the configuration with graph builds
Validate conversion accuracy against known mappings
Submit a pull request with the new configuration

Getting Help

If you have questions or need help:

General questions: Open a GitHub Discussion
Bug reports and features: Use the Issue Tracker
Direct contact: See Credits

We appreciate all contributions, no matter how small. Thank you for helping make IDTrack better!