From ee00bb3df9a618e3f01ce4145e729ca0ed6c4fb0 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 16 Sep 2026 00:47:13 +0200 Subject: [PATCH] docs: separate user and contributor guides --- README.md | 14 +++----------- docs/development.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 11 deletions(-) create mode 100644 docs/development.md diff --git a/README.md b/README.md index 6cc345f..0dc8d61 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Beffroi-specific repositories. Runtime rendering requires Bash, jq, Typst 0.15 or newer, standard POSIX utilities, and the fonts selected by the report. The examples use DejaVu Sans -and DejaVu Sans Mono. Python and uv are used only for tests. +and DejaVu Sans Mono. ## Render a report @@ -68,17 +68,9 @@ Record the Reportist revision, `typst --version`, and installed font files when recreating a historical document. PDF bytes can vary across Typst or font versions even when the report content and layout remain equivalent. -## Testing +## Contributing -Run validation, rendering, branding, pagination, and standalone tests in a -uv-managed environment: - -```bash -make test -``` - -Poppler's `pdfinfo` and `pdftotext` enable additional pagination and extracted -text checks when installed. +See the [contributor guide](docs/development.md). ## License diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..ccec821 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,41 @@ +# Development + +This document covers contributor workflows for Reportist. Rendering and report +authoring are documented in the main [README](../README.md) and +[report contract](report-contract.md). + +## Test environment + +Tests require uv and Typst. The Makefile creates `.venv`, synchronizes the pinned +packages from `requirements.txt`, and invokes Python only from that environment. + +```bash +make test +``` + +Poppler's `pdfinfo` and `pdftotext` enable additional pagination and extracted +text checks. Those checks are skipped when Poppler is unavailable. + +The suite covers JSON and YAML input, contract failures, optional fields, +replaceable branding, asset safety, overwrite behavior, pagination, extracted +content, and rendering from a standalone component copy. + +## Contract maintenance + +`schema/report.schema.json` is the public report interface. Keep the jq +production validator, Typst assertions, examples, and test oracle aligned with +the schema. Preserve version 1 compatibility or introduce a documented new +version and migration path. + +## Visual changes + +Exercise all supported content blocks and inspect representative PDFs after +changing templates, typography, colors, spacing, headers, footers, or pagination. +Record the Typst version and installed fonts because they can affect layout and +PDF bytes. + +## Repository boundaries + +Reportist stays generic. Do not add diagnostic interpretation, Beffroi branding, +incident storage, publication, or packaging. Production validation and rendering +remain shell, jq, and Typst based; Python stays under `tests/`.