beffroi-tools/docs/ci.md

3.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. SCM credentials, webhooks and the publication mount are administrator setup. CI checks formatting, Clippy, rustdoc, Python/Rust tests, real-media parity and whole-workspace Rust coverage. It never creates tags or release artifacts.

Parity reuses FFmpeg, FFprobe and Typst from PATH when available. Otherwise scripts/ci_tools.py fetches checksum-verified FFmpeg/FFprobe on Linux x86-64 and installs locked typst-cli 0.13.1 with Cargo under ignored downloads/ci-tools/. No sudo is needed; missing tools require network access and a first-time Typst build can take several minutes. To provision locally:

export PATH="$PWD/downloads/ci-tools/bin:$PATH"
python3 scripts/ci_tools.py

A test, provisioning or parity failure still fails the build, but does not skip the independent coverage stage. The test-passed marker requires all of them 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 --all-features --json --summary-only --output-path coverage/summary.json

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 and parity 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/Beffroi/beffroi-tools/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.