reportist/docs/development.md

42 lines
1.5 KiB
Markdown

# 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. `test.sh` creates `.venv` and synchronizes the pinned
packages from `requirements.txt`, and invokes Python only from that environment.
```bash
./test.sh
```
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 Typst
production validator, template 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 and Typst based; Python stays under `tests/`.