42 lines
1.5 KiB
Markdown
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/`.
|