pptx-reporter/docs/development/ci.md

4.7 KiB

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:

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):

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):

The renderer matches the maintained script from Dandaedre/agent-tasks, revision 8923682b958de698c5ec41f4275bfc6f7e44a2f6, rechecked against the coverage task. 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 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 for paths, prerequisites and update behavior.