beffroi-reporting/docs/operations.md

61 lines
2.8 KiB
Markdown

# Editing, building, and publishing
## Setup and editing
Run `./beffroi.sh bootstrap` after cloning to initialize the pinned Reports
and Reportist submodules. `./beffroi.sh doctor` checks the core tools. Edit
source files in `reports/reports/` or add a raw capture to
`reports/diagnostics/`; implementation changes belong in Reportist. Consult
[the report input contract](../reporter/docs/report-contract.md) for authored
YAML/JSON and [the diagnostic plugin](../reporter/plugins/diagnostics/README.md)
for raw capture behavior.
Render one source while editing:
```bash
./beffroi.sh report reports/reports/2026-09-04-clevo-handoff.yaml /tmp/report.pdf
./beffroi.sh diagnostic-pdf reports/diagnostics/windows_system_report_DESKTOP-SAU019H_20260915_121057.json /tmp/diagnostic.pdf
```
`capture-pdf` is a compatibility alias for `diagnostic-pdf`. For evidence
processing, `./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT NEW_OUTPUT_DIR
REFERENCE_TIME [AUTHOR] [THEME]` writes both `diagnostic.json` and
`report.pdf`. The PDF renderer reads the raw capture directly.
## Local verification
Run `./beffroi.sh test` before publishing. It executes Reportist's report and
diagnostic suites, checks the stored source set, builds all PDFs, and compares
all seven reports and ten diagnostics to the recorded legacy baseline. The
original renderer in `legacy/typst_reporter` is retained as a read-only local
reference. Its ignored `build/` PDFs enable raster comparison when available;
CI can still check recorded page counts and text hashes without them.
Build the complete publication with:
```bash
./beffroi.sh all build/publication --replace
./beffroi.sh all build/publication --replace --include-json
```
`--replace` builds beside the existing directory, then swaps it after success.
`--include-json` adds authored report JSON exports and copies raw capture JSON
beside the PDFs. Single-document rendering refuses an existing PDF unless
`--force` is supplied.
## CI and delivery
On `main`, the macro Jenkinsfile checks out pinned submodules, runs tests,
builds the publication, creates password-protected AES ZIP archives, archives
them as CI artifacts, and copies `Reports.zip` and `Diagnostics.zip` to its
configured deployment directory. Jenkins supplies `REPORT_ZIP_PASSWORD` from
credentials. The password must not be committed or printed. The standalone
Reportist Jenkinsfile runs plugin tests. Reports Jenkinsfile checks YAML and
JSON syntax only.
`./beffroi.sh package BUILD_DIR ARTIFACT_DIR` runs the same packaging locally
when `REPORT_ZIP_PASSWORD` is set. It requires `uv` and pinned `pyzipper`.
Package output is checked by reopening the archives. Publication and deployment
are external actions; review generated sources and artifacts before pushing a
change that triggers the main-branch pipeline.