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
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:
parent
a0bc786801
commit
847b96e624
21
README.md
21
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
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
Subproject commit bc319ece292fdfbcdc9ef475930f3878f6235771
|
||||
Subproject commit 3b139c15db42ff8b4da08faf1171617b1526a31f
|
||||
|
|
@ -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.
|
||||
2
reporter
2
reporter
|
|
@ -1 +1 @@
|
|||
Subproject commit 1d04ac9b44074682438b596fdb686fdcba5a0655
|
||||
Subproject commit ee00bb3df9a618e3f01ce4145e729ca0ed6c4fb0
|
||||
2
reports
2
reports
|
|
@ -1 +1 @@
|
|||
Subproject commit dbf247773c6e73197d4f5bab18f3c28381a7bb6a
|
||||
Subproject commit c92480d603d7b633d90029f13fd0ae80c85837ec
|
||||
Loading…
Reference in New Issue