5.3 KiB
Development and packaging
Rust compatibility
The bridge supports Rust 1.85.1 and newer. Rust does not publish long-term
support toolchains; 1.85.1 was chosen as a conservative distribution anchor
because it is shipped by Debian 13 stable. Cargo.toml declares the MSRV,
Cargo.lock pins an MSRV-compatible graph, and Jenkins checks that graph with
both Rust 1.85.1 and current stable.
Future dependency updates must preserve this check or deliberately update the
declared MSRV, documentation, and Jenkins value together. Cargo's MSRV-aware
resolver is enabled in .cargo/config.toml to avoid selecting newer compatible
crate releases that require a newer compiler.
Bridge checks
Run the same core checks as Jenkins before submitting a bridge change:
cargo +1.85.1 check --locked --all-targets --all-features
cargo +1.85.1 test --locked --all-targets --all-features
cargo fmt --all -- --check
cargo check --locked --all-targets --all-features
cargo test --locked --all-targets --all-features
cargo clippy --locked --all-targets --all-features -- -D warnings
Coverage
Jenkins uses pinned cargo-llvm-cov 0.9.0 with the current stable toolchain.
To generate the same reports locally, install the tool and llvm-tools-preview,
then run:
rustup component add llvm-tools-preview
cargo install cargo-llvm-cov --locked --version 0.9.0
cargo llvm-cov clean --workspace
cargo llvm-cov --locked --all-features --html --output-dir coverage
cargo llvm-cov report --json --summary-only --output-path coverage/summary.json
cargo llvm-cov report --lcov --output-path coverage/lcov.info
scripts/render-coverage-badge.sh \
"$(cargo llvm-cov report --summary-only | awk '$1 == "TOTAL" { gsub(/%/, "", $10); print $10 }')" \
coverage/coverage.svg
CI archives the HTML report, LCOV data, JSON summary, and SVG badge. There is no coverage floor yet because the initial bridge has no meaningful automated test suite. Add a ratcheted line-coverage floor once behavior tests exist; never add brittle tests merely to improve the percentage.
For public reports, configure the Jenkins job or node environment variable
COVERAGE_PUBLISH_ROOT to the absolute path of the mounted coverage directory.
Successful main builds publish immutable artifacts under:
MadGobblins/vsg-bridge-ls/<full-commit-id>/
The main symlink is updated only after the complete commit directory has been
moved into place. The README badge and report link use:
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/coverage.svg
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/html/
The web server should receive this mount read-only, disable directory listing, serve SVG with a restrictive content security policy, and apply long immutable cache headers only to commit-addressed paths. Retention may remove old commit directories, but should preserve tagged releases and every commit referenced by the stable alias.
Companion VSG fork
The fork keeps its stream-support patch small and rebases it onto upstream
master. From the fork checkout:
./update-fork.sh
./build-package.sh
To build and publish with an explicit Gitea token file:
chmod 600 ../gitea_token.txt
./build-package.sh ../gitea_token.txt --publish
The script builds both a wheel and source distribution and uploads only the
artifacts produced by that invocation. It also accepts GITEA_TOKEN or
GITEA_TOKEN_FILE when no positional token file is supplied.
Jenkins package publishing
The VSG Jenkins pipeline publishes successful master builds automatically.
It fetches repository tags before setup so setuptools-git-versioning can
derive the package version, then publishes the same wheel and source archive
that passed the pip and uv installation checks. Other branches never receive
the publishing credential.
Create the credential in Jenkins:
- Create a Gitea personal access token whose
packagepermission is set to Read and Write. Use an account allowed to publish packages owned by theMadGobblinsorganization. - Open Manage Jenkins → Credentials, select the narrowest folder or system store containing the multibranch job, and choose Add Credentials.
- Select Secret text, paste the token into Secret, and set ID to
vsg-gitea-package-token. - Save it. The Credentials Binding plugin must be installed for the
withCredentialspipeline step.
The token exists only as GITEA_TOKEN inside the publish stage. Shell tracing
is disabled before it is mapped to uv's UV_PUBLISH_PASSWORD; it is never put
in a command argument or written into the workspace.
Published versions come from the existing Git-versioning backend. An exact release version requires a version tag on the commit; untagged commits receive the backend's post-release version. Because package versions are immutable in Gitea, the pipeline uses uv's index check to skip files already present.