fix(docs): load the player from latest, not a pinned minor - #3320
Merged
Conversation
The catalog pages pinned the player CDN URL to a minor line, and that pin sat one line behind after the last release. Every page kept rendering, on the older build, so nothing surfaced it: the only symptom was that a fix published to npm never appeared on the docs. The generator derived its pin from the player's package.json, which is correct only if every page is regenerated on the release that moves it. That is the step that did not happen, and it has to happen across 175 generated pages plus three hand-written files for the pin to be true. A version carried in step across 178 places will be stale, and stale here is silent. Ask for latest instead and there is nothing to carry. This costs the ability to hold the docs back from a bad player release. Paid deliberately: the pin did not buy that either, it only delayed the good releases too. A test asserts no pinned version comes back, and fails if it stops finding the references at all, so it cannot pass by matching nothing.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
The pin guard hand-rolled a recursive directory walk with its own skip list and size cap, which the audit flagged: helpers living in a test file earn no coverage, so their complexity lands straight on the CRAP score. git already knows which files to read, and ignores node_modules and build output for us, so one call replaces the walker and both findings go away.
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.
What
The catalog pages load the player from a CDN. That URL pinned a minor line, and the pin was a line behind: it still asked for
0.7after the repo moved to0.8.Every reference now asks for
latest, in the three hand-written files and the 175 generated pages, plus a test that fails if a pin comes back.Why
The failure mode is the reason this is worth changing rather than bumping.
A stale pin does not break anything visibly. The page renders, the preview plays, the controls work, all on the older build. The only symptom is that a fix published to npm never reaches the docs, which shows up weeks later as "that bug is still there" rather than as a red check. Nobody greps 178 files for a version.
The generator already derived its pin from the player's
package.json, which is correct only if every page is regenerated on the release that moves the line. That is the step that did not happen. Getting it right permanently means carrying one version in step across 175 generated pages and three hand-written files, on every minor, forever.latestremoves the thing that has to be carried.What this costs. The docs can no longer be held back from a bad player release. That is real, and it is paid deliberately: the pin did not buy that control either, because it was not being moved on purpose. It only delayed the good releases too. A deliberate hold is still available by pinning again, at which point the test says so out loud instead of the pin rotting quietly.
Timing. jsDelivr serves
latestwiths-maxage=43200andmax-age=604800, so a newly published player reaches the edge within about twelve hours, and a reader with a warm cache within a week.How
scripts/generate-catalog-pages.tsemits@latestinstead of interpolating the player's minor version, and the 175 pages it owns were regenerated.docs/snippets/variables-explorer.jsx,docs/snippets/catalog-overview-player.jsxanddocs/catalog/index.mdxare hand-written and were changed directly.scripts/player-cdn-pin.test.tswalksdocs,scripts,packagesandregistryand asserts every player CDN reference asks forlatest. It also asserts it found more than a hundred references, so it cannot pass by matching nothing, and it checks the generator's own constant so a regeneration cannot quietly reintroduce a pin across every page.Test plan
Unit tests added/updated
Manual testing performed
Documentation updated (if applicable)
bun run test:scripts: 184 Node tests and 29 catalog Vitest tests passed, up from 182 with the two added here.The new test was confirmed to fail, not just pass: reintroducing
@0.7in one page turns it red and names the file.curlon thelatestURL returns 200 withx-jsd-version: 0.8.0, so the URL this ships resolves to a real build rather than a 404 on 178 pages.oxlintandoxfmtclean on the changed sources.Nothing here changes what a page does once the script loads. The diff is one URL, repeated.