beffroi-tools/docs/development/README.md

65 lines
3.1 KiB
Markdown

# Development
[Documentation](../README.md) · [CI and coverage](ci.md) · [Releases](releases.md)
## 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 and release helpers |
| `docs/` | Tool usage and specialized workflows |
Prototype in Python, then add a Rust workspace member when the workflow is
stable. Retire the Python implementation once the Rust port is validated.
The PPTX reporter is now Rust-only; the document exporter remains Python.
The [rundown converter](../rundown-converter/README.md) is a separate Rust workspace member
with CLI and egui interfaces. Its [implementation checklist](../rundown-converter/plan.md)
and [evaluation corpus](../rundown-converter/corpus.md) track coverage and remaining limitations.
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
```
Rust regression tests cover archive parsing, trimming, loops, report formats,
Ontime, CLI errors and GUI state; both PDF layouts compile with the embedded
engine. Probe-process tests use a controlled stub. No external FFmpeg, FFprobe
or Typst CLI is required for CI. The application still needs FFprobe at runtime.
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).
The converter can run without desktop dependencies using
`cargo run --locked -p rundown-converter --no-default-features --bin rundown-converter -- --help`.
Its tests generate synthetic XLSX inputs and never require private source files
or network downloads. The existing workspace test, lint, Rustdoc and coverage
commands include both tools; reporter release packaging remains separate.
The [ASCII filename cleaner](../ascii-names/README.md) is a separate Rust workspace member.
Run `cargo run --locked -p ascii-names` for its drag-and-drop window, or pass a
folder for CLI cleanup. It uses the same workspace checks and coverage gates.