beffroi-reporting/docs/development.md

1.9 KiB

Development

This document covers contributor setup and verification for the Beffroi Reporting integration workspace. User installation and report generation remain in the main README.

Test dependencies

Tests require the runtime dependencies plus uv. Python is used only by the test suites and always runs in virtual environments created by uv venv and synchronized by uv pip.

Reportist can use Poppler's pdfinfo and pdftotext for additional pagination and extracted-text checks. Those checks are skipped when Poppler is unavailable.

Run the complete verification

make check

This invokes the component suites and a sanitized capture-to-PDF integration test. Coverage includes:

  • diagnostic contracts, evidence integrity, fixtures, and the rule catalog;
  • immutable draft generation, regeneration, branding, races, and no-replace publication;
  • Reportist contract validation, rendering, assets, pagination, and standalone use;
  • capture analysis, report adaptation, validation, and PDF rendering as one workflow.

The same entry point is used by Jenkins through scripts/check-components.sh.

Component changes

Commit changes in the owning component repository first. Then commit its updated submodule pin in this integration repository. Historical integration commits must continue to identify exact compatible component revisions.

Before committing an integration change, run:

./bootstrap.sh --check
make check
git diff --check
git submodule status

Push component commits and the integration commit together with:

git push --recurse-submodules=on-demand

Repository boundaries

Keep orchestration in this repository. Diagnostic rules belong in Win Diagnostics, investigation content belongs in Beffroi Reports, and rendering logic belongs in Reportist. Do not introduce dependencies from a component back to this workspace.