docs(web): consolidate 4.0 docs to one v4.0 line, drop stale snapshot#2827
Conversation
…snapshot
The version switcher now labels the 4.0 stable docs "v4.0 (current)" instead of
"v4.0.0" on both guides and api. 4.0.0/4.0.1/4.0.2 share one per-minor docs tree
(v4-0-0), so freezing the label at the GA patch made the live docs look stale.
Removed the vestigial v4-0-1-snapshot guides tree. It was a pre-GA fork that fell
behind v4-0-0 (missing the reorganized deploy command tree; its deploy nav was
empty). Both sites deploy from develop, so in-progress patch docs already live in
v4-0-0 directly -- a separate snapshot tree is only warranted when a different
minor/major (e.g. v4-1-snapshot) is under development.
Salvaged the one page unique to the snapshot, upgrading/changelog.mdx ("Reading
the Changelog"), into v4-0-0 and wired it into the Upgrading sidebar group (it was
an orphan even in the snapshot). Added courtesy redirects /v4-0-1-snapshot/* ->
/v4-0-0/* for the high-traffic landings.
Also dropped now-dangling snapshot references: verify-docs DEFAULT_TARGET, the
docs root version index, STYLE.md, the writing-docs site-layout note, and two
component comment examples.
Verified: guides (432 pages) and api (2739 pages) build clean; the salvaged page
renders at /v4-0-0/upgrading/changelog/; redirect stubs emit meta-refresh to
/v4-0-0/.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>
github-actions
Bot
added
docs
javascript
![wheels-bot[bot]](https://avatars.githubusercontent.com/in/3657588?s=60&v=4){kind=small}
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: This is a docs-only housekeeping PR that removes the stale pre-GA v4-0-1-snapshot guides tree, relabels the version switcher to "v4.0 (current)", salvages the one unique snapshot page into v4-0-0, and cleans up all dangling references. The rationale is sound, the execution is thorough, and no CFML code is touched. Verdict: comment — two minor nits below, nothing blocking.
Correctness
Everything in the PR body checks out against the diff:
web/packages/ui/src/data/versions.ts— snapshot entry dropped, bothGUIDES_VERSIONSandAPI_VERSIONSrelabeled tov4.0✓web/sites/guides/astro.config.mjs— five courtesy redirects added ✓web/sites/guides/src/content/docs/v4-0-0/upgrading/changelog.mdx— salvaged page present, wired inv4-0-0.jsonsidebar under Upgrading ✓- Dangling refs cleaned up in
STYLE.md,writing-docs.mdx,verify-docs.mjs,index.md,EditLink.astro,PageTitle.astro✓ - No
v4-0-1-snapshotreferences remain anywhere underweb/packages/orweb/sites/guides/src/(grep confirms) ✓
One item to watch: the test plan has [ ] CI doc-build + link-check workflows green unchecked. Not a blocker for review, but don't merge before that goes green.
Docs
Nit 1 — Redirect coverage is thinner than the GA rename.
web/sites/guides/astro.config.mjs lines 97–104 add five v4-0-1-snapshot redirects. The prior v4-0-0-snapshot → v4-0-0 rename added nine (root, installing, tutorial, first-15-minutes, release-channels, cfml-engines, installation, two cli-reference entries). The snapshot set omits start-here/first-15-minutes, start-here/release-channels, start-here/cfml-engines, and command-line-tools/installation.
The PR author explains the asymmetry: the dev channel had "little backlink equity." That is a reasonable call given the snapshot was never listed in the stable version-switcher entry. But if you want parity with the GA rename, four more entries would do it:
'/v4-0-1-snapshot/start-here/first-15-minutes': '/v4-0-0/start-here/first-15-minutes/',
'/v4-0-1-snapshot/start-here/release-channels': '/v4-0-0/start-here/release-channels/',
'/v4-0-1-snapshot/start-here/cfml-engines': '/v4-0-0/start-here/cfml-engines/',
'/v4-0-1-snapshot/command-line-tools/installation': '/v4-0-0/command-line-tools/installation/',Not required — the existing comment in astro.config.mjs already acknowledges the limitation — just flagging in case any of those paths ever got indexed.
Nit 2 — No CHANGELOG entry.
The project tracks docs fixes in CHANGELOG.md (see the #2777 and #2801 entries for comparable docs-only work). The version-switcher relabel and snapshot retirement have no entry. A one-liner under ### Changed would keep the log consistent:
- Version switcher now labels the 4.0 stable docs "v4.0 (current)" (was "v4.0.0"); the
vestigial pre-GA v4-0-1-snapshot guides tree is removed and its one unique page,
"Reading the Changelog", is salvaged into v4-0-0/upgrading/. (#2827)
Not a blocker — purely a consistency nit given existing docs-fix CHANGELOG precedent.
Commits
Single commit docs(web): consolidate 4.0 guides/api onto one v4.0 line, drop stale snapshot — valid type + scope per commitlint.config.js, 64-char subject (under the 100-char limit), sentence-case, DCO-signed (Signed-off-by: Peter Amiri). Commit body accurately describes the motivation and full scope of the change.
Wheels Bot — Reviewer B (round 1)A's review is clean. Both nits are factually grounded, no false positives detected, no missed issues on re-scan. A's "comment" verdict is appropriate given the explicitly non-blocking nature of the findings, and I concur. Marking converged-approve. SycophancyNone detected. A gave a "comment" verdict (not approve), and every positive statement in the Correctness section is backed by a specific file/line verification. False positivesOne minor count discrepancy: A says the prior All other claims check out:
Missed issuesNone. This is a docs-only PR. No CFML touched, so cross-engine invariants are not in scope. No security surface. No migrations. Verdict alignmentA's "comment" verdict is consistent with the findings: two explicitly non-blocking nits and one pending CI checkbox. Requesting changes for optional improvements the author already explained would be disproportionate. ConvergenceAligned. A's nits are accurate and non-blocking; I have no remaining disputes or missed-issue findings. The PR is review-clean for this SHA pending CI green. The human author can choose whether to add the CHANGELOG entry or the four extra redirects — neither is required to merge. |
… guides baseline Addresses wheels-bot review feedback on #2827. CHANGELOG: add an [Unreleased] section with a one-liner under ### Changed, matching the docs-fix precedent set by #2777 / #2801. Restores the [Unreleased] heading that #2824's promote-to-4.0.2 removed. Redirects: four additional /v4-0-1-snapshot landings for parity with the GA v4-0-0-snapshot rename precedent -- first-15-minutes, release-channels, cfml-engines, command-line-tools/installation. Verified each stub emits meta-refresh to the matching /v4-0-0/ URL. Visual baseline: refresh web/tests/visual-baselines/guides.png to reflect the intended UI changes from the prior commit -- the version switcher now reads "v4.0 (current)" and the Upgrading sidebar group has a new "Reading the Changelog" entry. Diff inspected against the CI artifact; the actual.png shows the expected changes (switcher label + sidebar item). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Peter Amiri <peter@alurium.com>
|
Addressed both review nits in bdcf4f3:
Also refreshed |
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: This is the follow-up commit addressing both nits from the prior round. Both have been resolved cleanly: the four missing snapshot redirects are now present and the CHANGELOG [Unreleased] entry is in place. The visual baseline was also refreshed to match the new version-switcher label and salvaged sidebar item. Verdict: approve -- no remaining issues.
Correctness
The new commit (bdcf4f341) addresses exactly what was flagged:
Nit 1 -- Redirect parity (addressed). The four redirects suggested in the previous review are present in web/sites/guides/astro.config.mjs:
'/v4-0-1-snapshot/start-here/first-15-minutes': '/v4-0-0/start-here/first-15-minutes/',
'/v4-0-1-snapshot/start-here/release-channels': '/v4-0-0/start-here/release-channels/',
'/v4-0-1-snapshot/start-here/cfml-engines': '/v4-0-0/start-here/cfml-engines/',
'/v4-0-1-snapshot/command-line-tools/installation': '/v4-0-0/command-line-tools/installation/',The order within the block is logical (root, then start-here/* paths, then command-line-tools/*), and the existing comment noting the "little backlink equity" rationale is unchanged.
Nit 2 -- CHANGELOG (addressed). CHANGELOG.md now opens with an [Unreleased] section containing a ### Changed entry. The placement is correct: [Unreleased] sits above [4.0.2], restoring the heading that the promote-to-4.0.2 commit (#2824) had removed. The prose entry accurately describes the relabel, the snapshot retirement, the salvaged page, and the redirect coverage.
Visual baseline. web/tests/visual-baselines/guides.png is updated (166,955 bytes -> 166,693 bytes). The commit message states the diff was inspected against the CI artifact before committing. The baseline must track the new version-switcher label ("v4.0 (current)") and the salvaged "Reading the Changelog" sidebar entry or the visual-regression step will fail on merge.
Commits
Two commits in this PR, both conformant with commitlint.config.js:
| SHA | Message | Valid? |
|---|---|---|
87c1b5f |
docs(web): consolidate 4.0 guides/api onto one v4.0 line, drop stale snapshot |
Yes -- type docs, scope web, 64 chars, DCO-signed |
bdcf4f3 |
docs(web): add CHANGELOG entry + 4 extra snapshot redirects + refresh guides baseline |
Yes -- type docs, scope web, 85 chars (under 100), DCO-signed |
Both carry Signed-off-by: Peter Amiri <peter@alurium.com>. DCO is satisfied.
Remaining pre-merge gate
The PR test plan still shows [ ] CI doc-build + link-check workflows green unchecked. Do not merge until that passes -- the visual-baseline update makes it especially important that CI confirms the actual rendered output matches the refreshed PNG.
Wheels Bot — Reviewer B (round 1)A's review of the follow-up commit is clean in substance. One minor factual error in the commit-length table, but it does not affect A's conclusion or verdict. Aligned on APPROVED; marking converged-approve. SycophancyNone detected. Every positive statement in A's review is backed by a specific file, line, or binary diff entry. False positivesOne minor factual error: A's commit table states the first commit (87c1b5f) is "64 chars". The actual subject line is All other claims verified against the diff: four new redirect entries (first-15-minutes, release-channels, cfml-engines, command-line-tools/installation) present in astro.config.mjs; CHANGELOG.md opens with [Unreleased] / Changed above [4.0.2] in correct format; visual baseline Bin 166955 -> 166693 bytes matches diff header; second commit 85 chars; both commits DCO-signed. Missed issuesNone. Docs-only follow-up (3 files: CHANGELOG.md, astro.config.mjs, guides.png). No CFML, no migrations, no security surface. Verdict alignmentA's APPROVED verdict is consistent with the findings: both prior nits verifiably addressed, no new issues introduced, CI gate noted rather than waved past. ConvergenceAligned. The one factual error (character count) does not affect the verdict. PR is review-clean for this SHA pending CI green. |
…s-version-cleanup
The committed web/tests/visual-baselines/blog.png predates #2825 (the 4.0.2 release post), so any PR that doesn't itself touch web/content/blog/posts/ trips Visual regression on the blog canary -- the live blog index now has the 4.0.2 post as the top entry, shifting older posts down by one position. The workflow's intended develop-side auto-refresh apparently did not land on the #2825 push (likely the same branch-rule push rejection that bites the pre-refresh-commit step on PR runs -- see the separate workflow-fix task). Updating the baseline here unblocks this PR; the underlying workflow gate fix is out-of-scope. Diff inspected against the CI artifact -- the change is exactly the new top-post reflow, no unintended layout shift. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Peter Amiri <peter@alurium.com>
|
Pushed dab3a94db — a one-PNG refresh of Diagnosis: the prior fixup ( So this PR now also carries the blog-baseline refresh that the develop-side auto-push apparently failed to land on #2825. Slightly off-topic for a docs-versioning PR, but it's the documented unblock path ("Download the visual-regression-diffs artifact and update baselines as needed") and once this lands, develop is no longer stale. The underlying workflow bug (the |
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: This is a follow-up to the previously approved round at `bdcf4f341`. Two new commits have landed since then: a merge from `develop` that brings in the 4.0.2 blog post (#2825), and a binary PNG update to refresh the blog visual baseline that the merge displaced. Both are clean and narrowly scoped. Verdict: comment — everything looks good; holding off on a formal approve only because the Visual regression CI check is still pending on the new head.
Correctness
Merge commit `391f20f67` — merges `origin/develop` (specifically `fc90371a3`, the 4.0.2 release post) into the PR branch. The merge introduces one file: web/content/blog/posts/wheels-4-0-2-released.md (+153 lines). No snapshot content, no conflict markers, no unintended files. Clean.
Commit `dab3a94db` — updates web/tests/visual-baselines/blog.png from 129,877 → 131,766 bytes. The commit message explains the causality correctly: the merged 4.0.2 post now heads the blog index, shifting older posts down by one position, which invalidates the prior baseline. The author states the diff was inspected against the CI artifact. No text files were touched.
Commits
| SHA | Message | Valid? |
|---|---|---|
391f20f67 |
Merge remote-tracking branch 'origin/develop' into worktree-peter+docs-version-cleanup |
Merge commit — exempt from type requirement; Validate Commit Messages passes ✓ |
dab3a94db |
chore(web): refresh stale blog visual baseline after #2825 |
Type chore, scope web, 44-char subject, DCO-signed (Signed-off-by: Peter Amiri) ✓ |
Pre-merge gate
The Visual regression check is still pending on the current head. This is the single check that the baseline update is designed to fix — do not merge before it completes and goes green. All other checks that have finished are passing.
Wheels Bot — Reviewer B (round 1)A's review is accurate in substance on this follow-up. One repeated false positive (character count, wrong again), no missed issues on a docs/binary-only pair of commits. Aligned on the "comment" verdict; marking converged-approve since A's only hold is a pending CI gate, not an actionable change request. SycophancyNone detected. A's positive statements are each backed by a specific file, byte count, or commit attribute. False positivesOne factual error: A's commit table states This is the third round in a row where A has miscounted subject lengths (round 2 on SHA All other claims verified:
Missed issuesNone. Both commits in scope are narrowly scoped: one merge commit bringing in a blog post (no CFML, no migrations, no config), one binary PNG update. Cross-engine invariants, security surface, and migration concerns are not in scope. Verdict alignmentA's "comment" verdict (holding off on formal approve pending the Visual regression check) is appropriate. The check is a gate condition, not a change request, and it is exactly the check the ConvergenceAligned. A has no actionable findings requiring author changes — the sole hold is a CI gate that the author cannot control. The one false positive (character count) does not affect A's recommendation. No missed issues remain. The PR is review-clean pending CI green. |
The "Commit pre-refreshed blog baseline" step pushes to develop, which branch protection rejects (GH013) on PR runs — failing the whole visual-regression job even when the regression check itself passed (observed on #2827). The workflow's own comments at lines 205-210 already document the post-merge blog-baseline auto-refresh as a push-only contract; this brings the step's `if:` into line with that intent. Trigger pattern: a PR behind develop where develop has merged a `web/content/blog/posts/` change since the branch point. detect-scope sees that file as "changed" in the PR diff, sets blog_content_changed, the pre-refresh regenerates the baseline, the regression check passes, and then the commit step fires and the push is rejected. Signed-off-by: Peter Amiri <peter@alurium.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 participant
Summary
The guides/api version switcher topped out at v4.0.0 and still listed a stale v4.0.1-SNAPSHOT dev entry, so the live docs looked frozen at the GA patch even though 4.0.2 has shipped. This adopts a per-minor docs convention for the 4.0 line and removes the vestigial snapshot.
v4-0-0tree, so the label tracks the line, not the GA patch (no more per-patch label churn). The URL slug is unchanged (/v4-0-0/), so no redirects/SEO risk for existing GA backlinks.v4-0-1-snapshotguides tree (190 files). It was a pre-GA fork that fell behindv4-0-0— missing the reorganizeddeploycommand tree, and its deploy nav was empty. Both sites deploy fromdevelop, so in-progress patch docs already live inv4-0-0directly; a separate*-snapshottree is only warranted when a different minor/major (e.g.v4-1-snapshot) is in development.upgrading/changelog.mdx("Reading the Changelog") — intov4-0-0/(git rename, history preserved) and wire it into the Upgrading sidebar group (it was an orphan even in the snapshot)./v4-0-1-snapshot/*→/v4-0-0/*for the high-traffic landings (root, start-here/installing, start-here/tutorial, command-line-tools).verify-docsDEFAULT_TARGET, the docs-root version index,STYLE.md, the writing-docs site-layout note, and two component comment examples.Test plan
grepfor residualv4-0-1-snapshotrepo-wide — only the intended redirect block remainspnpm --filter @wheels-dev/site-guides build— 432 pages, clean; salvaged page renders at/v4-0-0/upgrading/changelog/; no snapshot content builtpnpm --filter @wheels-dev/site-api build— 2739 pages, clean/v4-0-1-snapshot/start-here/installing/emits<meta http-equiv="refresh" ... url=/v4-0-0/start-here/installing/>🤖 Generated with Claude Code