Skip to content

Contribution Guide

Thank you for your interest in contributing to BrkRaw. This guide explains how the project is extended, and clarifies which kinds of changes belong in core versus addons or plugins.

We welcome contributions across a wide range of areas, including:

  • New sequence support (rules, specs, and converter hooks)
  • Custom reconstruction pipelines (FID-based or other specialized paths)
  • Image denoising or ML-powered workflows
  • CLI plugins and tooling built on top of the BrkRaw API

Before opening an issue or pull request, please start with a GitHub Discussion so we can align on scope and choose the appropriate extension path. For core changes, we follow a clear progression:

Discussion proposal → Issue(s) → Pull request

We track a shared .vscode/ directory to provide consistent tasks and settings across contributors.

1) Create a virtual environment and install development dependencies:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

  1. In VSCode, select the workspace interpreter (.venv/bin/python).

  2. Optional: run predefined tasks from the Command Palette:

  3. Setup: venv + deps

  4. MkDocs: Serve
  5. Release: Prep (bump + notes)

CLI extensions

BrkRaw supports CLI extensions through an entrypoint mechanism, allowing new subcommands to be developed and distributed independently of the core repository.

  • Entrypoint group: brkraw.cli
  • Intended for custom workflows or project-specific helpers

See reference/addons-and-plugins.md for an overview of the extension model.

Extension points

Most customization can be implemented without modifying core code:

  • Install rules, specs, and transforms using the addon CLI
  • Define or update runtime context_map entries to map scanner context to specs, rules, and transforms
  • Provide converter_hook overrides for specialized conversion logic
  • Ship standalone CLI plugins via the brkraw.cli entrypoint

Rule, spec, and transform workflow

Rules determine which specs and converter hooks apply to a given scan. Specs map Bruker parameter files into structured outputs. Transforms are Python helpers used during spec evaluation.

This composition model enables conditional workflows, such as applying different metadata schemas per sequence, without editing core code.

Recommended references:

  • reference/rules.md
  • reference/specs.md

Converter hooks (custom conversion)

Converter hooks override conversion helpers such as get_dataobj, get_affine, and convert. They are registered via the brkraw.converter_hook entrypoint and may be selected conditionally by rules.

This design allows sequence-specific reconstruction pipelines while preserving BrkRaw's standard handling of metadata, sidecars, and output layouts.

Converter hooks are especially useful for custom MRI sequences with bespoke reconstruction requirements. In most cases, they should be packaged as small, independent plugins.

Layout design and data structure

The layout system constructs output paths and filenames from metadata using one of the following mechanisms:

  • layout_entries: structured entries with key, entry, and sep
  • layout_template: string templates with {Key} placeholders

Defaults may be defined in config.yaml or in context_map.__meta__, and can be overridden at runtime via the API or CLI.

See reference/layout.md for details.

Core development policy

Core changes are limited to maintaining compatibility with Paravision layouts and metadata conventions. All other customization should be implemented as addons (rules, specs, transforms, context maps) or external plugins.

If you believe a change must live in core, start with a GitHub Discussion and explain why the behavior cannot be implemented through existing extension mechanisms. Once agreed, open issue(s) for the scoped work and combine them into a single pull request.

Defaults we welcome contributions for

We actively welcome proposals for default rules and specs to ship with BrkRaw, particularly for modality-specific workflows. If you work with specific Bruker sequences, consider contributing:

  • Improved info_spec mappings for brkraw info or BrukerLoader.info
  • metadata_spec mappings aligned with BIDS or lab standards
  • Rules that select specs based on method, acqp, or visu_pars
  • Reusable context_map patterns for common lab workflows

Documentation contributions are also valuable, including:

  • End-to-end use cases combining rules, specs, and context maps
  • Modality-specific tutorials (for example DWI, fMRI, or MRS)
  • Corrections or clarifications to existing documentation

Even small improvements, such as clearer parameter labels, are useful. Please open a Discussion with sequence details and the parameter files you rely on.

Packaging and distribution

We encourage authors to package addons and plugins as standalone repositories so they can be installed and versioned independently. This simplifies sharing tools across labs and projects.

Release and publishing (GitHub Actions)

BrkRaw uses two GitHub Actions workflows:

  • Create Release: tag push → GitHub Release
  • Publish Package: release → PyPI or TestPyPI

PyPI publishing uses Trusted Publishing (OIDC), so no API token is required.

Release flow (tag-based)

  1. Update the version and release notes locally.
  2. Create and push a tag:
git tag vX.Y.Z
git push origin vX.Y.Z
  1. Create Release runs automatically and creates a GitHub Release.
  2. When the Release is published, Publish Package runs automatically.

Release flow (manual)

  1. Open GitHub Actions → Create Release → Run workflow.
  2. Enter the tag (for example vX.Y.Z) and run.
  3. The workflow checks out the tag and creates the Release.
  4. Publishing proceeds automatically after the Release is published.

Publish-only flow (manual)

  1. Open GitHub Actions → Publish Package → Run workflow.
  2. Choose the target (testpypi or pypi).
  3. Optionally specify a tag. If provided, the workflow validates that the tag matches the version in pyproject.toml.

Notes:

  • Pre-release tags (a, b, rc) create GitHub pre-releases and skip PyPI publishing.
  • The publish workflow validates that the tag matches the package version.

Community

If you build something useful, please start a GitHub Discussion. We plan to periodically highlight community addons and plugins on the BrkRaw site.

Contributors

See docs/dev/contributors.md for the current list of contributors.