docs: separate user and contributor guides
Beffroi Reporting CI Beffroi Reporting integration CI failed.
Beffroi/beffroi-reporting/pipeline/head There was a failure building this commit Details

This commit is contained in:
Dandaedre 2026-09-16 00:47:21 +02:00
parent a0bc786801
commit 847b96e624
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
5 changed files with 66 additions and 20 deletions

View File

@ -30,10 +30,6 @@ The compiler builds a small helper used for atomic, no-replace publication.
Selected report fonts must also be installed; the examples use DejaVu Sans and
DejaVu Sans Mono.
Tests additionally require uv. Python is used only by the test suites, always in
uv-managed virtual environments. Poppler's `pdfinfo` and `pdftotext` enable
optional PDF inspection tests.
## Installation
Clone the workspace with its pinned submodules and run bootstrap:
@ -92,19 +88,6 @@ make render REPORT=... OUTPUT=...
Run `make help` for the complete command summary.
## Verification
Run all component suites and the sanitized capture-to-PDF integration test:
```bash
make check
```
The tests create isolated uv environments inside each component. They cover the
diagnostic contracts and rule catalog, immutable and racing publication,
Reportist validation and rendering, replaceable branding, and the complete
pipeline.
## Reproducibility
Git submodules pin exact component commits instead of following branch heads.
@ -113,6 +96,10 @@ Typst version, and installed font files when reproducing a historical report.
PDF bytes can vary across Typst and font versions even when content and layout
remain equivalent.
## Contributing
See the [contributor guide](docs/development.md).
## License
Root-level orchestration software is licensed under the MIT License. Diagnostic

@ -1 +1 @@
Subproject commit bc319ece292fdfbcdc9ef475930f3878f6235771
Subproject commit 3b139c15db42ff8b4da08faf1171617b1526a31f

59
docs/development.md Normal file
View File

@ -0,0 +1,59 @@
# 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
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:
```bash
./bootstrap.sh --check
make check
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 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.

@ -1 +1 @@
Subproject commit 1d04ac9b44074682438b596fdb686fdcba5a0655
Subproject commit ee00bb3df9a618e3f01ce4145e729ca0ed6c4fb0

@ -1 +1 @@
Subproject commit dbf247773c6e73197d4f5bab18f3c28381a7bb6a
Subproject commit c92480d603d7b633d90029f13fd0ae80c85837ec