Contributing Guide

Contributions to TERRA are welcome — bug reports, bug fixes, documentation, and new features. This guide summarizes the essentials to get started.

Development install

git clone https://github.com/Lotfollahi-lab/terra.git
cd terra
pip install -e ".[dev,test,doc]"

Code style

TERRA uses pre-commit to enforce a consistent code style (ruff for linting and formatting, plus prettier). Enable it once in your clone:

pre-commit install

Hooks then run automatically on every commit, fixing issues or reporting errors.

Tests

TERRA uses pytest. Please add tests for new functionality. Run the suite from the repository root:

pytest

Continuous integration runs the tests on dev and on pull requests against the minimum and a recent supported Python version, plus a pre-release-dependencies job to catch upstream incompatibilities early.

Documentation

Documentation is built with Sphinx and MyST-NB. Notebooks placed in docs/notebooks are rendered as tutorials. Public functions and classes use NumPy-style docstrings. Build the docs locally with:

cd docs
make html
open _build/html/index.html

Releasing

Bump the version in pyproject.toml following Semantic Versioning (MAJOR.MINOR.PATCH). Then create a GitHub release with a vX.Y.Z tag — this triggers the workflow that builds and publishes the package to PyPI.