Development workflow

Development workflow#

A substantial change to the public API is described in an issue before a pull request is opened; small fixes and documentation corrections go directly to a pull request. Work on a topic branch of a fork, one coherent change per branch.

Change procedure#

  1. Read AGENTS.md, and the implementation and tests of the code being changed.

  2. Change the code and the documentation of the public behaviour it affects. Generated files are regenerated, not edited.

  3. Run the checks:

    Change

    Command

    Python

    ./scripts/lint.sh: ruff’s format and lint checks and codespell; --fix applies ruff’s formatting and fixes

    Any code

    ./scripts/run_tests.sh, or a subset of the suite during development

    C, CUDA or the ABI

    The full suite; python scripts/check_device.py on a machine with a CUDA device

    Documentation

    ./scripts/build_docs.sh (warnings are errors), and ./scripts/build_docs.sh --execute for changed examples

    PDF manual

    ./scripts/build_docs_pdf.sh, after python -m playwright install chromium

  4. Commit, push to the fork, and open a pull request (Pull requests).

A topic branch takes upstream changes by rebasing, which rewrites its history:

git fetch upstream
git rebase upstream/main
git submodule update --init --recursive

Pull requests#

A pull request is opened against pulserver/bartorch:main from a topic branch, as a draft while work remains. Its description follows the repository’s template:

Section

Contents

What changed

A concise summary

Why

The problem, the issue it addresses and, for a new method, the paper

Validation

The commands run and their results; for a numerical change, the reference and the tolerance; hardware or optional dependencies that were not available

Public API and documentation

Changes to public behaviour and the documentation updated for them

CI runs on every pull request:

Workflow

Checks

Tests

The suite on Linux with GCC 14, and on macOS and Windows with clang, each on Python 3.10 and 3.14; a CUDA build, tested on the host because the runner has no device

Lint, Typos

./scripts/lint.sh, and codespell

Docs

./scripts/build_docs.sh, the reference rendered without the compiled library, when docs/ or src/ changes. The executed gallery and the PDF manual are built when a maintainer comments /build-docs on the pull request

Publish to PyPI

Every wheel built, repaired and tested as a release would be, when the pull request changes the build (CMakeLists.txt, cmake/, pyproject.toml, src/cuda/, src/bartorch/_lib.py or the workflow)

A pull request is merged when CI passes and a maintainer has approved it.

Generated files#

File

Generator

Test holding it

src/bartorch/_abi.py

python scripts/gen_abi.py, from src/csrc/include/bartorch.h

tests/test_abi.py

src/bartorch/_catalogue.py

python scripts/gen_catalogue.py, from BART’s command declarations

tests/test_catalogue.py

Logo, mark, architecture and encoding figures in docs/_static/

python scripts/make_artwork.py

None

Plots in docs/_static/figures/

python scripts/make_figures.py [module], from scripts/figures/

None

run_tests.sh regenerates both Python files before the suite. The logo’s sources and their terms are listed in License and third-party notices. The documentation’s build products, docs/generated/, docs/api_objects.rst, docs/auto_examples/ and the PDF manual, are not tracked; ./scripts/build_docs.sh --clean removes them.

Published documentation#

The docs workflow publishes into the gh-pages branch, one directory per version: latest from main, and vX.Y.Z from a release tag, which scripts/publish_docs.py also copies to stable when it is the newest release. The site root redirects to stable, or to latest before the first release, and the version switcher reads versions.json beside the directories.

BART submodule updates#

external/bart pins a revision of the downstream fork pulserver/bart (BART fork). Moving it is a change of its own: sync the fork, update the submodule pointer, run python scripts/gen_catalogue.py, and review the resulting API differences. tests/test_tools.py requires every BART command to be wrapped by hand, generated into bartorch.tools, or listed as private with a reason in src/bartorch/_coverage.py.

FINUFFT submodule updates#

external/finufft is upstream FINUFFT at one commit, unmodified. Moving it is a change of its own: choose a commit whose upstream CI passed, update the submodule pointer, record the commit and the reason in the pull request, and run the suite on every platform. tests/test_finufft.py holds the transform against explicit discrete Fourier sums and against BART’s gridder. A change FINUFFT needs goes upstream, not into the checkout.

Tests#

A numerical test compares BART with a reference outside BART: an independent FFT or DFT, an explicit sum, a closed-form signal, a finite difference or an adjoint identity. Comparing two entry points into the same BART implementation establishes nothing about its correctness. Tests are pytest functions whose names state the property tested.

Code of conduct#

Our pledge#

We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our standards#

Behaviour that helps:

  • showing empathy and kindness toward other people

  • respecting differing opinions, viewpoints, and experiences

  • giving and gracefully accepting constructive feedback

  • accepting responsibility, apologising to those affected by our mistakes, and learning from the experience

Behaviour that is not acceptable:

  • sexualised language or imagery, and sexual attention or advances of any kind

  • trolling, insulting or derogatory comments, and personal or political attacks

  • public or private harassment

  • publishing others’ private information, such as a physical or email address, without their explicit permission

Enforcement#

Report abusive, harassing, or otherwise unacceptable behaviour to matteo.cencini@gmail.com. All complaints will be reviewed and investigated promptly and fairly. The maintainers will respect the privacy and security of the reporter of any incident.

Maintainers who do not follow or enforce this code in good faith may face temporary or permanent repercussions as determined by other maintainers.

Attribution#

Adapted from the Contributor Covenant, version 2.1.