Skip to content

Check the documented ModelJars version against Central, not just against itself - #354

Merged
bsbodden merged 1 commit into
mainfrom
docs/modeljars-0.1.76
Nov 3, 2026
Merged

bsbodden merged 1 commit into
mainfrom
docs/modeljars-0.1.76

Conversation

@bsbodden

@bsbodden bsbodden commented Nov 3, 2026

Copy link
Copy Markdown
Member

The value, and the reason it keeps going stale

The docs advertised ModelJars 0.1.75 while Central serves 0.1.76. #350 had just corrected
them from 0.1.65 against a published 0.1.75 — ten releases, and 0.1.65 predates the ONNX intake
and the speech loader, so a reader following the docs got a runtime that could not load models the
catalog advertises
. 0.1.76 then shipped an hour after that correction, so the fix left it one
release behind.

verifyDocumentation was never going to catch either case. It keeps the five pages that
interpolate {modeljars-version} consistent with the modeljarsVersion property — and the property
is the thing that is wrong. Nothing resolves it: no module depends on ModelJars, no lockfile pins
it, so no build fails when it drifts.

I flagged exactly this gap in #350 and deferred it as "a separate change". It recurred within the
hour. That settles whether it was worth deferring.

The guard

scripts/verify-modeljars-currency.py takes Maven Central as the authority, for the reason
ModelJars' verify-site-version.mjs states: a source tag does not prove a reader can resolve the
dependency the documentation shows.

  • Unreachable Central exits non-zero, rather than waving the check through. A check of this
    shape "first shipped doing nothing" in this repo's history, and that is the mechanism.
  • Accepts an explicit released version, so proving it can fail does not need the network — the
    same argument verify-site-version.mjs takes.
  • Registered in scripts/integrity/mutation-check.py with the 0.1.65 defect as its mutation,
    because this repo's own rule is that a guard which cannot detect the defect it was written for is
    worse than no guard.
clean tree  -- ok  modeljars-currency/documented-version-behind-central
mutated     -- ok  guard caught: documentation advertising ModelJars 0.1.65 against a published 0.1.76
every one of 9 guards passes clean and fails on its own defect.

Gates

verifyDocumentation, verifyReleaseMetadata, complianceCheck — BUILD SUCCESSFUL.
scripts/integrity/mutation-check.py — 9 of 9.

…nst itself

The documentation advertised ModelJars 0.1.75 while Central served 0.1.76. Earlier today it
advertised 0.1.65 against a published 0.1.75 -- ten releases, and 0.1.65 predates the ONNX intake
and the speech loader, so a reader following the docs got a runtime that could not load models the
catalog advertises. Fixing that value is what left it one release behind: 0.1.76 shipped an hour
after the correction.

verifyDocumentation was never going to catch either. It keeps all five pages that interpolate
{modeljars-version} consistent with the modeljarsVersion property, and the property is what is
wrong. Nothing resolves it -- no module depends on ModelJars and no lockfile pins it -- so no build
fails when it goes stale. I noted this gap when correcting 0.1.65 and deferred it; it recurred
within the hour, which answers whether it was worth deferring.

scripts/verify-modeljars-currency.py takes Maven Central as the authority, for the reason
ModelJars' own verify-site-version.mjs gives: a source tag does not prove a reader can resolve the
dependency the documentation shows. Unreachable Central exits non-zero rather than passing, since a
check that waves through on network failure is how this shape of check first shipped doing nothing.

It accepts an explicit released version so the mutation check does not depend on the network, which
is also how verify-site-version.mjs is driven. Registered in scripts/integrity/mutation-check.py
with the 0.1.65 defect as its mutation: all 9 guards pass clean and fail on their own defect.

verifyDocumentation, verifyReleaseMetadata and complianceCheck pass.
@bsbodden
bsbodden merged commit 30bf5a2 into main Nov 3, 2026
38 checks passed
@bsbodden
bsbodden deleted the docs/modeljars-0.1.76 branch November 3, 2026 18:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant