[DOCS] ci/docs-versions: catch version drift automatically - #61
Open
alexandrecarvalheira wants to merge 2 commits into
Open
[DOCS] ci/docs-versions: catch version drift automatically#61alexandrecarvalheira wants to merge 2 commits into
alexandrecarvalheira wants to merge 2 commits into
Conversation
Stale versions are the failure this repo keeps hitting. The last sweep moved 72 pins across six pages, and on several of them the install command and the table beside it had already drifted apart from each other. The script treats the compatibility page as the single source of truth and fails when anything else disagrees. It reads two forms, an explicit package@1.2.3 pin and a table row pairing a package with a version, which is what let those two drift independently before. Two guards keep it quiet. A version written package@v1.2.3 reads as a historical reference, which is how the FHE.sol pages date a rename, and a line carrying <!-- versions:ignore --> opts out. Verified in both directions on the current repo: clean over 114 files, and it reports both forms when a stale pin is planted. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…eekly Two jobs, split by whether they need the network. The pull request job asks only whether the docs agree with the compatibility page. It is offline, so a release published while a pull request is open cannot fail it. The scheduled job asks whether the compatibility page still agrees with npm, and opens an issue when it does not. It never runs on a pull request, because someone else shipping a version is not that pull request's problem. A second week of drift comments on the open issue instead of filing a duplicate. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Layer 1 of the snippet-checking plan. Small, offline on pull requests, and aimed squarely at the regression that started this whole effort.
What it checks
scripts/check-versions.pytreats the compatibility page as the single source of truth.--docsasserts every version pinned anywhere in the docs matches that page. Offline.--npmasserts the compatibility page itself matches what is published. Networked.The last sweep moved 72 stale pins across six pages, and on several of them the install command and the package table beside it had already drifted apart from each other. So the script reads both forms: an explicit
package@1.2.3pin, and a table row pairing a package with a version.Two guards against noise
A checker that cries wolf gets switched off, so:
package@v1.2.3reads as a historical reference and is never checked. That is how theFHE.solpages date a rename ("Renamed incofhe-contracts@v0.1.3"), and those must not be rewritten.<!-- versions:ignore -->opts out, for prose that deliberately shows an old version.Verified in both directions
@v0.1.2/@v0.1.3refsversions:ignoreline--npmreports it, exit 1The workflow, and why it is two jobs
Split by whether the job needs the network:
On pull requests, only the offline consistency check runs. A package published while your PR is open cannot fail it. This is the same reasoning as leaving
--check-externaloff in the Mint check.On a weekly schedule, the npm check runs and opens an issue when the compatibility page falls behind. It never runs on a pull request, because someone else shipping a version is not that PR's problem. A second week of drift comments on the existing issue rather than filing a duplicate.
STYLE.md documents the new checker alongside Vale and
lint-docs.py, including the two opt-out forms.actionlintclean on all workflows.mint validateandmint broken-linkspass.Layers 2 (TypeScript
tsc --noEmit) and 3 (Foundry compile) follow in their own PRs.🤖 Generated with Claude Code