beffroi-tools/docs/ci.md

84 lines
3.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.
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:
```sh
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:
```sh
cargo llvm-cov --locked --workspace --all-features --json --summary-only --output-path coverage/summary.json
```
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 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):
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/version.svg
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/test.svg
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/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.