61 lines
2.8 KiB
Markdown
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.
|