ci: fast docs format check for docs-only PRs#2028
Open
fengmk2 wants to merge 10 commits into
Open
Conversation
Since #1991, docs-only PRs skip the full CI matrix, so nothing format-checks markdown: the only formatting check (vp check in cli-e2e-test) never runs for them. Add a docs-fmt job that runs only when code-changed is false. It installs the released Vite+ via setup-vp (version pinned to latest because the workspace vite-plus version can be ahead of the registry) and runs vp fmt --check over the whole repo, covering docs/** and all root markdown. Loading the root vite.config.ts needs the runtime 'vite-plus' import to resolve, so the job links the released package out of the global install instead of installing the workspace, which keeps the job under a minute. Non-blocking by design: the job is not listed in the done job's needs. Ref: #1991 (comment)
Temporarily lift the code-changed == 'false' condition (this PR edits ci.yml, so the job would otherwise be skipped here) and add an intentionally misformatted canary file. Revert this commit before merge.
✅ Deploy Preview for viteplus-preview canceled.
|
Second half of the demo: with the misformatted file gone, the docs-fmt job should now go green on this PR. The lifted skip condition still needs to be restored before merge.
Both demo runs are linked from the PR: the job failed on the canary file and passed after its removal. With the guard back, docs-fmt only runs when code-changed is false.
fengmk2
commented
Jul 3, 2026
vp resolves oxfmt project-first (process.cwd() before its own bundled copy), so installing the pnpm catalog's pinned oxfmt and linking it into node_modules makes the check follow the repo's real formatter version instead of whatever the released vite-plus bundles. The two match today (0.57.0), but the pin protects against drift in either direction. oxfmt loads the fmt block from vite.config.ts itself and resolves the config's vite-plus import from its own realpath, so the temp install also gets a vite-plus sibling link.
cli-e2e-test (linux) already bootstraps the global CLI from source on every main push, so snapshot that install (before the upgrade/implode tests mutate it) into an actions cache keyed by commit. docs-fmt restores the newest main build and runs its local CLI, so docs-only PRs are checked with a vp built from the same code they are based on. When no cache is available (cold repo, evictions), the job falls back to the released vite-plus from setup-vp, which also provides Node.js for the local CLI in both paths. The repo-pinned oxfmt overlay stays, so the formatter version always follows the PR's own catalog pin either way.
Lift the docs-fmt skip condition and the main-only cache save so both paths can be observed here: the first run falls back to the released vp (no cache yet), and a docs-fmt rerun after cli-e2e-test (linux) completes restores the branch cache. Reverted before merge.
The dev global install is not relocatable: install-global-cli wires local-dev installs by symlinking node_modules/vite-plus to the workspace packages/cli and transitive deps into its node_modules, so caching ~/.vite-plus/current captures a 4 MB skeleton of dangling symlinks (verified on this PR: the saved cache was 4 MB instead of ~160 MB). Making it self-contained would require a release-style pack-and-install pipeline, which is not worth it for a format check whose formatter version is already pinned via the oxfmt overlay. Back to the released vp launcher with the repo-pinned oxfmt.
The released vite-plus bundles the oxfmt it was tested with (currently the same 0.57.0 the repo pins), and the formatter rarely changes behavior between releases. If version drift ever produces confusing results here, the project-first overlay from 9adcc4c can be brought back.
cpojer
approved these changes
Jul 3, 2026
cpojer
reviewed
Jul 3, 2026
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
2 participants
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.
Since #1991, docs-only PRs skip the full CI matrix, so nothing format-checks markdown (
vp checkin cli-e2e-test only runs for code changes). As suggested in this comment, add a fastdocs-fmtjob that runsvp fmt --checkwhencode-changed == 'false'.How it stays fast (about 15s total on the runner, the check itself is about 5s for 1,879 files):
setup-vpinstalls the released Vite+ (version: latest, since the workspacevite-plusversion can be ahead of the registry) withrun-install: false.vp fmtneeds the rootvite.config.tsto load, and its runtimeimport ... from 'vite-plus'must resolve. Instead of installing the whole workspace (which also needs the vite/rolldown subrepo clones), the job symlinks the releasedvite-pluspackage out of the global install intonode_modules/.**/*.mdpart of the CI skip filter.Non-blocking as suggested: the job is not listed in the
donejob's needs.Verified on this PR by temporarily lifting the skip condition (middle commits, since ci.yml itself is a code change the job would otherwise skip here):
The final commit restores the
code-changed == 'false'guard, so the job is expected to be skipped on this PR itself.