pptx-reporter/docs/development/ci.md

100 lines
4.7 KiB
Markdown

# CI and coverage
Jenkins must use a Multibranch Pipeline supplying `BRANCH_NAME`, with the
`rust_no_docker` worker, Python 3.11+ and Rust.
The current worker runs in a FreeBSD jail; the Tools stage logs `uname -sr`.
SCM credentials, webhooks and the publication mount are administrator setup.
CI checks formatting, Clippy, rustdoc, Python/Rust tests and
whole-application Rust coverage. It also builds the mdBook manual and publishes
successful non-PR main builds to `/mnt/books/manuals/`. It never creates tags or
release artifacts.
CI uses the Rust reporter's regression tests and embedded PDF engine, plus
Python CI and packaging tests. It does not provision FFmpeg, FFprobe or the
Typst CLI. FFprobe remains an application runtime dependency and is fetched
separately when packaging portable releases.
A test failure still fails the build but does not skip the independent coverage
stage. The test-passed marker requires all required tests to succeed; fresh
measured coverage can therefore accompany a failing test badge.
## Measurement
CI installs pinned `cargo-llvm-cov 0.9.1` and `llvm-tools-preview`. The tracked
`.cargo/config.toml` alias `cargo coverage` expands to:
```sh
cargo llvm-cov --locked --workspace --json --summary-only --output-path coverage/summary.json
```
Coverage includes the GUI, PDF engine and all production Rust code.
Run the same lifecycle locally (no publication):
```sh
python3 scripts/ci.py init
python3 scripts/ci.py coverage
python3 scripts/ci.py finalize
```
The enforced floor is **75% line coverage**, configured in `coverage.toml`.
Ordinary production code, GUI and PDF code remain included. The gate compares
unrounded covered/count totals, logs the measurement and floor before PASS/FAIL,
and retains tool failure status even when a valid measurement exists.
`init` removes stale output. CI creates `.tests-passed-${BUILD_NUMBER}` only
after all required tests pass. A valid measurement creates
`.coverage-ready-${BUILD_NUMBER}` even below the floor. Cleanup preserves that
measurement; unavailable coverage becomes neutral `-%`. Temporary
`coverage/summary.json`, diagnostics and markers are deleted after processing.
Generated badges and reports are ignored, never committed.
## Badges
In `post { cleanup }`, Jenkins reads the version from root
`Cargo.toml` → `workspace.package.version`, renders current-build status, and
archives exactly these files with fingerprints and `allowEmptyArchive: false`:
- `coverage/version.svg`
- `coverage/test.svg`
- `coverage/coverage.svg`
Only non-PR `main` builds publish, including failed builds, under
`/mnt/assets/coverage/idle-org/pptx-reporter/main/`. The POSIX publication script
validates sources and destination components, writes atomically and never
synchronizes or prunes the shared mount.
Public URLs (also referenced once each below the README title):
- https://assets.dandaedre.com/coverage/idle-org/pptx-reporter/main/version.svg
- https://assets.dandaedre.com/coverage/idle-org/pptx-reporter/main/test.svg
- https://assets.dandaedre.com/coverage/idle-org/pptx-reporter/main/coverage.svg
The renderer matches the maintained script from `Dandaedre/agent-tasks`,
revision `8923682b958de698c5ec41f4275bfc6f7e44a2f6`, rechecked against the
[coverage task](https://proxy.dandaedre.com/gitea/Dandaedre/agent-tasks/raw/branch/main/tasks/ci-coverage-badges.task.md).
`tests/test_ci_badges.py` covers threshold boundaries, tool failures, missing
measurements, SVG validation and safe publication to temporary directories.
Actual Jenkins archival/publication and public URL retrieval are separate
external checkpoints. Local checks do not establish that badges are live.
The asset server should mount assets read-only, disable listings, serve SVG
with restrictive CSP, and revalidate mutable URLs or use a short cache lifetime.
## Project manuals
The Tools stage installs the mdBook version pinned in
[`docs/manuals/mdbook-version`](../manuals/mdbook-version) and requires `rsync`.
The Build manuals stage stages existing documentation, builds the manual, and
checks rendered links, anchors and downloadable assets. No mdBook plugins or
additional Jenkins plugins are needed. Tests cover staging and publication into
temporary directories, including stale-file cleanup and preservation of unrelated
manuals. Publication runs after coverage, only when the whole build is successful,
on non-PR main. The helper independently enforces the branch/PR restriction.
The worker must expose the existing writable `/mnt/books` mount. The manual and
landing page are published under `/mnt/books/manuals/`; deletion is scoped to
the owned `pptx-reporter` directory. This keeps the existing badge cleanup behavior intact.
See [manual configuration, preview and publication](../manuals/README.md) for
paths, prerequisites and update behavior.