beffroi-reporting/docs/development.md

61 lines
2.0 KiB
Markdown

# Development
This document covers contributor setup and verification for the Beffroi
Reporting integration workspace. User installation and report generation remain
in the main [README](../README.md).
## 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
```bash
scripts/check-components.sh
```
This invokes the component suites and a sanitized capture-to-PDF integration
test. Coverage includes:
- diagnostic contracts, evidence integrity, fixtures, and the rule catalog;
- draft generation, regeneration, branding, and unique destination handling;
- 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:
```bash
./bootstrap.sh --check
scripts/check-components.sh
git diff --check
git submodule status
```
Push component commits and the integration commit together with:
```bash
git push --recurse-submodules=on-demand
```
## Repository boundaries
Keep orchestration in this repository. Diagnostic analysis and rules belong in the Reports diagnostic plugin,
investigation content belongs in Beffroi Reports, and common rendering
logic belongs in Reportist. Additional plugins implement the same preparation
contract described in `reporter/README.md`. Do not introduce dependencies from a component back
to this workspace.