vsg-bridge-ls/doc/development.md

158 lines
6.3 KiB
Markdown

# 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:
```sh
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:
```sh
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:
```sh
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:
```sh
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 91.49%, 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:
```text
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:
```text
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:
```sh
./update-fork.sh
./build-package.sh
```
To build and publish with an explicit Gitea token file:
```sh
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
- [Language Server Protocol 3.17](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/)
- [tower-lsp stdio example](https://github.com/ebkalderon/tower-lsp/blob/master/examples/stdio.rs)
- [upstream VSG](https://github.com/jeremiah-c-leary/vhdl-style-guide)
- [upstream VSG documentation](https://vhdl-style-guide.readthedocs.io/en/latest/)