From 847b96e6244c134a1b2ffa83c984b85ab365892e Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 16 Sep 2026 00:47:21 +0200 Subject: [PATCH] docs: separate user and contributor guides --- README.md | 21 +++------------- diagnostics | 2 +- docs/development.md | 59 +++++++++++++++++++++++++++++++++++++++++++++ reporter | 2 +- reports | 2 +- 5 files changed, 66 insertions(+), 20 deletions(-) create mode 100644 docs/development.md diff --git a/README.md b/README.md index 2d4eb52..6dc9072 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/diagnostics b/diagnostics index bc319ec..3b139c1 160000 --- a/diagnostics +++ b/diagnostics @@ -1 +1 @@ -Subproject commit bc319ece292fdfbcdc9ef475930f3878f6235771 +Subproject commit 3b139c15db42ff8b4da08faf1171617b1526a31f diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..bf7989f --- /dev/null +++ b/docs/development.md @@ -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. diff --git a/reporter b/reporter index 1d04ac9..ee00bb3 160000 --- a/reporter +++ b/reporter @@ -1 +1 @@ -Subproject commit 1d04ac9b44074682438b596fdb686fdcba5a0655 +Subproject commit ee00bb3df9a618e3f01ce4145e729ca0ed6c4fb0 diff --git a/reports b/reports index dbf2477..c92480d 160000 --- a/reports +++ b/reports @@ -1 +1 @@ -Subproject commit dbf247773c6e73197d4f5bab18f3c28381a7bb6a +Subproject commit c92480d603d7b633d90029f13fd0ae80c85837ec