Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
64 lines (41 loc) · 2.77 KB

CONTRIBUTING.md

File metadata and controls

64 lines (41 loc) · 2.77 KB
Raw

Contributing to DiGeo

We welcome bug fixes, new features, documentation improvements, and examples or applications. This guide explains how to set up a development environment, run the existing test suite, update the documentation, and follow good practices that keep the project healthy.

Local Development Setup

  1. Fork and clone the repository, then create a topic branch off main.
  2. We recommend a virtual environment (venv, conda, or uv) so dependencies stay isolated.
  3. Install DiGeo in editable mode with the tooling extras:
pip install --no-build-isolation -e .[test,doc]

This builds the package locally and installs testing and documentation dependencies. If you modify kernels, you will need to rebuild the package after changes.

Coding Standards

  • Follow the existing module layout under src/digeo/ and prefer small, composable functions with type hints.
  • Keep public APIs documented with docstrings; reference math notation when it helps users understand the geometry. It is also helpful to link relevant examples or tutorials in the docstrings.
  • Run Ruff locally before opening a PR:
ruff check src tests

Running Tests

The test suite lives in tests/ and is collected via pytest.

pytest
  • GPU-dependent tests automatically skip when CUDA is unavailable. Still, please run them on at least one CUDA-enabled machine if your change touches kernels.
  • Enable pytest verbosity (-vv) and set CUDA_LAUNCH_BLOCKING=1 to surface kernel traces.

Documentation Workflow

All documentation sources live under doc/source/ and are built with Sphinx.

cd doc
make clean && make html
  • Autogenerated API pages in doc/source/generated/ are created by sphinx-autosummary; edit the corresponding docstrings instead of the generated files.
  • Add new tutorials under doc/source/user_guide/, and applications of DiGeo in doc/source/applications/. These sections are meant to be more narrative and less API-focused, so feel free to include diagrams, math, and code snippets that illustrate the concepts.
  • Keep figures in _static/, and credit external assets.

Pull Request Checklist

  • Rebuild the package, pip install --no-build-isolation -e . when modifying kernels.
  • Tests (pytest) and lint (ruff check) pass locally.
  • Documentation builds without warnings (make html).
  • New public APIs include docstrings and, where appropriate, examples. If applicable, update the what's new section in the docs.
  • Add tests for any new functionality or bug fixes, and ensure they run on both CPU and GPU if applicable. If you rely on CUDA-specific behavior, verify on a GPU build and mention the CUDA/PyTorch versions.
  • The PR description links related issues and calls out remaining TODOs or follow-ups.

Thank you for helping improve DiGeo!