vsg-bridge-ls/doc/development.md

6.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

After installing a newly built companion VSG wheel, run the opt-in real-process integration check as well:

VSG_EXECUTABLE=/path/to/venv/bin/vsg \
  cargo test --test packaged_vsg -- --ignored

Normal unit tests use injected runners and do not depend on a developer's VSG installation.

Run the two network-enabled dependency policy gates before the core checks:

cargo audit --deny warnings
cargo deny check

Coverage

Jenkins uses pinned Cargo Tarpaulin 0.37.5 with its LLVM engine and the current stable toolchain. To run the same 90% line-coverage gate locally:

rustup component add llvm-tools-preview
cargo install cargo-tarpaulin --locked --version 0.37.5
cargo tarpaulin --config tarpaulin.toml

CI uses a temporary JSON summary to render the coverage SVG badge. Its final cleanup action obtains the package version from cargo pkgid --locked, with a Cargo.toml fallback, and renders the test badge from a build-specific marker written only after the test stage succeeds. If coverage did not complete, CI renders a neutral -% badge instead of leaving a broken or stale image. Jenkins archives only those three badges. The first behavior-test pass reached 84.38% (81/96 lines); end-to-end byte-stream and protocol lifecycle tests raised current coverage above 90%. The latest coverage run measured 90.27%, allowing CI to enforce a 90% floor. Raise that floor only after coverage remains stable under useful tests; never add brittle tests or production branches merely to improve the number.

Standalone HTML, JSON, and LCOV files produced locally remain ignored. Badges are generated only by Jenkins and are not tracked in the repository. Jenkins does not retain precise reports; it keeps only coverage/coverage.svg, coverage/version.svg, and coverage/test.svg.

For the public badge, the Jenkins worker exposes the shared assets/ directory at /mnt/assets, beside the existing /mnt/books mount. The pipeline sets BADGE_PUBLISH_ROOT to /mnt/assets/coverage; the worker creates that directory when needed, and its parent must be writable. The final cleanup action atomically replaces all three badges after every main build, including failed builds:

MadGobblins/vsg-bridge-ls/main/coverage.svg
MadGobblins/vsg-bridge-ls/main/test.svg
MadGobblins/vsg-bridge-ls/main/version.svg

main is a real world-traversable directory, not a symlink. This avoids web server symlink restrictions. Precise HTML, JSON, and LCOV reports are not retained. The README uses these mutable CI badge URLs:

https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/coverage.svg
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/test.svg
https://assets.dandaedre.com/coverage/MadGobblins/vsg-bridge-ls/main/version.svg

The web server should receive this mount read-only, disable directory listing, serve SVG with a restrictive content security policy, and use a short cache or revalidation for the mutable badge URL.

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:

  1. Create a Gitea personal access token whose package permission is set to Read and Write. Use an account allowed to publish packages owned by the MadGobblins organization.
  2. Open Manage Jenkins → Credentials, select the narrowest folder or system store containing the multibranch job, and choose Add Credentials.
  3. Select Secret text, paste the token into Secret, and set ID to vsg-gitea-package-token.
  4. Save it. The Credentials Binding plugin must be installed for the withCredentials pipeline 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.

References