Developer Guide

Developer Guide#

This guide covers the practical workflow for developing in the coordinax workspace. It is aimed at contributors working on code, tests, and documentation.

  • Use contributing.md for pull request expectations and contribution checklist items.

  • Use maintainers.md only for maintainer-focused release and operational tasks.

Before You Change Code#

Read the relevant specification before editing behavior.

  • The root specification in spec.md is authoritative for the main coordinax package.

  • Workspace packages may define their own package-local specification files under packages/*/docs/spec.md.

  • If code, tests, or docstrings disagree with the relevant spec, update them to match the spec.

This is especially important for charts, frames, manifolds, embeddings, vector semantics, and transform rules.

Workspace Layout#

This repository is a UV workspace with one main package and several workspace packages:

  • src/coordinax/: main package

  • packages/coordinax.api/: abstract dispatch API

  • packages/coordinax.astro/: astronomy-specific frames and transforms

  • packages/coordinax.hypothesis/: Hypothesis strategies used throughout the test suite

  • packages/coordinax.interop.astropy/: optional Astropy interoperability

The root test and docs trees exercise the whole workspace, so even a small change in one package can surface in root docs or shared tests.

Environment Setup#

Clone the repository and install the development dependency group with UV:

git clone https://github.com/GalacticDynamics/coordinax.git
cd coordinax
uv sync --group dev --extra workspace

This installs the local development toolchain, including nox, pytest, prek, docs dependencies, and the workspace packages used by the full contributor workflow.

If you prefer to run tools without activating a shell environment, use uv run ... directly. For example:

uv run nox -s test
uv run nox -s docs

Daily Workflow#

A typical change looks like this:

  1. Read the relevant spec and inspect the existing implementation.

  2. Make the code, test, and documentation changes together.

  3. Run the narrowest useful checks first.

  4. Run the broader pre-PR checks before opening or updating a pull request.

For example:

# Fast feedback while iterating
uv run pytest tests/unit/distances -q
uv run nox -s "pylint(package='coordinax')"
uv run nox -s "ty(package='coordinax')"

# Broader validation before a PR update
uv run nox -s lint
uv run nox -s test
uv run nox -s docs

If your change affects multiple packages or shared semantics, run the broader checks earlier rather than relying on a narrow path-only test run.

Nox Sessions#

The authoritative session definitions live in the repository root noxfile.py. The most useful sessions are:

Main Sessions#

  • uv run nox -s all: runs the default contributor gate: lint, test, and docs.

  • uv run nox -s lint: runs prek, pylint, and ty.

  • uv run nox -s test: runs the default test session.

  • uv run nox -s docs: builds the documentation.

Linting and Type Checks#

  • uv run nox -s precommit: runs all prek/pre-commit hooks.

  • uv run nox -s "pylint(package='coordinax')": run Pylint for the main package.

  • uv run nox -s "pylint(package='api')": run Pylint for coordinax.api.

  • uv run nox -s "pylint(package='astro')": run Pylint for coordinax.astro.

  • uv run nox -s "pylint(package='hypothesis')": run Pylint for coordinax.hypothesis.

  • uv run nox -s "ty(package='coordinax')": run ty check on the main package plus coordinax.api.

  • uv run nox -s "ty(package='api')", uv run nox -s "ty(package='astro')", uv run nox -s "ty(package='hypothesis')": run ty check for a specific workspace package.

Testing#

  • uv run nox -s "pytest(package='coordinax')": test the root package paths: README.md, docs, src/, and tests/.

  • uv run nox -s "pytest(package='api')": test packages/coordinax.api/.

  • uv run nox -s "pytest(package='astro')": test packages/coordinax.astro/.

  • uv run nox -s "pytest(package='hypothesis')": test packages/coordinax.hypothesis/.

Pass additional pytest arguments after --. For example:

uv run nox -s "pytest(package='coordinax')" -- tests/unit/charts -q
uv run nox -s "pytest(package='hypothesis')" -- -k distances

Documentation#

  • uv run nox -s docs: build HTML docs.

  • uv run nox -s docs -- --serve: build docs with live reload via sphinx-autobuild.

  • uv run nox -s docs -- -b linkcheck: check external links.

  • uv run nox -s build_api_docs: regenerate API reference source files under docs/api/.

Packaging#

  • uv run nox -s build: build an sdist and wheel.

Release operations are documented separately in the repository root RELEASING.md.

Testing Guidance#

The test suite combines ordinary unit and integration tests with documentation testing through Sybil.

  • Root package work is typically tested through tests/, src/, docs/, and README.md.

  • Package-specific work should also run that package’s own tests under packages/<name>/.

  • Documentation code blocks are part of the test surface, so doc updates should be validated with the test or docs sessions.

Prefer property-based tests when you are checking mathematical laws, invariants, or compatibility with JAX transformations. When relevant, use strategies from coordinax.hypothesis rather than hand-rolled examples.

Changes to JAX-facing behavior should be tested with the same assumptions the project uses elsewhere:

  • scalar-first behavior

  • compatibility with jax.jit and jax.vmap

  • correct behavior under multiple dispatch

Documentation Workflow#

Build the docs locally while you work:

uv run nox -s docs

For live reload in a browser:

uv run nox -s docs -- --serve

Useful documentation tasks:

  • run uv run nox -s docs -- -b linkcheck after adding new links

  • run uv run nox -s build_api_docs if API reference stubs need to be regenerated

  • run uv run nox -s "pytest(package='coordinax')" -- docs when you want doc-focused test feedback

Package-Specific Work#

When editing a workspace package under packages/, check whether that package has its own docs/spec.md and package-local tests and docs.

In practice:

  • update code, tests, and docs in the package together

  • keep cross-package semantics consistent with the root spec.md

  • run the package-local pytest session and any affected root sessions

For example, work in coordinax.hypothesis often needs both package-local tests and root tests that consume those strategies.

Pre-PR Checklist#

Before opening or updating a pull request, contributors should usually run:

uv run nox -s lint
uv run nox -s test
uv run nox -s docs

If the change is broad or you want the closest local approximation to CI, run:

uv run nox -s all

Use contributing.md for the pull request checklist and contribution norms.