beffroi-tools/docs/development.md

48 lines
2.0 KiB
Markdown

# Development
## Layout and workflow
| Directory | Purpose |
| --- | --- |
| `tools/` | Python prototypes and document utilities |
| `tests/` | Python regression and CI/packaging tests |
| `crates/<tool>/` | Rust ports, each with its own source, tests and assets |
| `scripts/` | Shared CI, parity and release helpers |
| `docs/` | Tool usage and specialized workflows |
Prototype in Python, then add a Rust workspace member when the workflow is
stable. Keep the Python implementation as a parity reference while useful.
Avoid speculative shared crates; extract common code when multiple tools need it.
The root `Cargo.toml` owns workspace metadata, the shared version and build
profiles. Members inherit that metadata. Keep one root `Cargo.lock` and `target/`.
The reporter is the default member; CI explicitly checks the entire workspace.
Use `-p pptx-reporter` to select it when building from a multi-tool workspace.
## Checks
Use a recent stable Rust toolchain. Python tools need 3.9+; CI helpers need 3.11+.
Run from the repository root:
```sh
cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
python3 -m unittest discover -s tests -v
cargo build --locked --workspace --all-features
python3 scripts/parity.py target/debug/pptx-reporter
```
Parity requires FFmpeg, FFprobe and the Typst CLI for the Python reference.
It compares JSON/Ontime for real media with trims, loops, custom timing and
orphan media, and generates every report format. Python exporter tests mock
external document applications. Inspect rendering changes visually as well.
`cargo build -p pptx-reporter --no-default-features` builds the CLI without the
GUI or PDF engine; add `--features pdf` to restore embedded PDFs.
Keep generated files out of Git. Commit each completed task after checks; do
not push without authorization. See [CI and coverage](ci.md) and
[cross builds and packaging](releases.md).