Skip to content

Core vs Addon Development

BrkRaw development follows two clearly separated paths:

  • Core updates: maintain compatibility with current and upcoming Paravision layouts, file structures, and metadata conventions.
  • Addons and plugins: implement rules, specs, transforms, context_map definitions, or custom CLI tooling without modifying core code.

This separation is intentional and helps keep the core stable while allowing rapid experimentation and customization through extensions.

When core changes are appropriate

Core changes are intentionally limited to Paravision compatibility and low-level loader or infrastructure concerns.

If you believe a change must live in core, start with a GitHub Discussion and explain clearly why the behavior cannot be implemented as an addon or plugin. Once there is agreement, open one or more scoped issues before submitting a pull request.

Using the shared VSCode setup

Core development should use the shared VSCode configuration to ensure consistent workflows 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 tasks available from the Command Palette:

  3. Setup: venv + deps

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