Contributing#

We welcome contributions! This page summarises the local development workflow. See AGENTS.md for the longer-form guide aimed at AI coding agents (which captures the same conventions).

Environment#

The canonical workflow uses uv, which resolves dependencies from pyproject.toml and manages the virtual environment for you:

$ git clone https://github.com/torchgeo/torchgeo-bench.git
$ cd torchgeo-bench
$ uv sync --extra dev

If you prefer conda, create an environment with a compatible Python first and run uv sync inside it:

$ conda create -n torchgeo-bench 'python>=3.12,<3.13'
$ conda activate torchgeo-bench
$ uv sync --extra dev

Makefile shortcuts#

The top-level Makefile provides convenient wrappers around the above:

Target

What it does

make install

Create / update the conda env and install [dev].

make sync

Alias for install.

make tests

pytest (skips slow integration tests).

make lint

pre-commit run --all-files.

make format

ruff format then ruff check --fix --select I.

make docs

Build HTML documentation into docs/_build/html.

make docs-clean

Remove the docs/_build directory.

make clean

Removes htmlcov, .coverage, .pytest_cache.

Linting and formatting#

We use ruff for both linting and formatting:

$ uv run ruff check .
$ uv run ruff format .

The project’s ruff configuration enables E, W, F, I, B, C4, UP, ARG, SIM, and D (pydocstyle, Google convention) checks. Line length is 100.

Tests#

$ uv run pytest                                  # all tests (skipping slow)
$ uv run pytest -m slow                          # only slow integration tests
$ uv run pytest tests/test_intrinsic_dim.py -v   # one file
$ uv run pytest -k "m-eurosat" -v                # by keyword
$ uv run pytest --no-cov                         # disable coverage for speed

Tests skip gracefully when data/ is missing — they look up the canonical subdirs documented in Datasets.

Code style#

  • Python 3.12+ throughout. Use modern type hints (list[str], X | None) — do not import from typing.List / Optional / Union.

  • Avoid from __future__ import annotations; prefer Self, quoted annotations, or explicit imports for forward references.

  • Google-style docstrings (configured via ruff.lint.pydocstyle.convention).

  • Use the logging module — no bare print calls.

  • No defensive try/except ImportError for hard dependencies — every package in [project.dependencies] is guaranteed to be installed.

Documentation#

This very site is built with Sphinx. The quickest way to build it locally is via the Makefile shortcut:

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

This assumes sphinx-build is on your PATH (install with uv sync --extra docs). To rebuild from scratch:

$ make docs-clean && make docs

Releasing to PyPI#

  1. Configure a PyPI Trusted Publisher for this repository with environment name pypi.

  2. Tag and push:

    $ git tag v0.2.0
$ git push origin v0.2.0

The Publish to PyPI workflow (.github/workflows/release.yml) builds and uploads the release automatically.