chore(web): post-GA docs rename — v4-0-0-snapshot → v4-0-0, seed v4-0-1-snapshot - #2612
Conversation
The v4.0.0 GA shipped today (2026-05-12). Renaming the URL slug from 'v4-0-0-snapshot' to 'v4-0-0' so the URL matches the now-stable channel status. Internal cross-link rewrites, astro redirects for the old URLs, versions.ts updates, and the new v4-0-1-snapshot clone follow in subsequent commits in this PR. Signed-off-by: Peter Amiri <peter@alurium.com>
…d dir to /v4-0-0/ After the directory rename in the previous commit, all the absolute cross-page links inside the docs still pointed at the old URL slug. Replaced /v4-0-0-snapshot/ with /v4-0-0/ in every .md/.mdx file under the renamed directory and in the renamed sidebar JSON. Each file's within-version structure is unchanged — same relative paths, same fragment anchors — just the version segment is corrected. Signed-off-by: Peter Amiri <peter@alurium.com>
versions.ts (single source of truth for both guides and api sites): - GUIDES_VERSIONS: replace v4-0-0-snapshot (snapshot) with v4-0-0 (current), demote v3-0-0 to archived, add new v4-0-1-snapshot (snapshot) for the next dev cycle. - API_VERSIONS: replace v4-0-0-snapshot (snapshot) with v4-0-0 (current), demote v3-0-0 to archived. No v4-0-1-snapshot yet because there's no docs/api/v4.0.1.json to generate against; the API site only adds a version slug when there's matching JSON to consume. astro.config.mjs: - Add explicit redirects for the high-traffic /v4-0-0-snapshot/ landing pages (root, installing, tutorial, first-15-minutes, release-channels, cfml-engines, command-line-tools/installation) so external bookmarks and SEO equity transfer to the new /v4-0-0/ slug. - Update the two Phase-0 cli-reference redirects to target /v4-0-0/ instead of /v4-0-0-snapshot/. Add the same redirect at the new slug too in case anyone hits /v4-0-0/cli-reference directly. Astro's static redirects map can't catch-all without getStaticPaths, so arbitrary deep links to /v4-0-0-snapshot/foo/bar/baz will 404 rather than redirect. The listed entries cover the URLs most likely to appear in external content (blog posts, README links, package descriptions). A Cloudflare-side wildcard could provide full coverage if SEO retention from deep-link backlinks turns out to matter post-GA. Signed-off-by: Peter Amiri <peter@alurium.com>
Ran `node web/scripts/generate-api-docs.mjs 4.0.0` to populate web/sites/api/src/content/docs/v4-0-0/ with 378 function pages across 9 sections (configuration, controller, global-helpers, migrator, model-*, view-helpers, etc.). The input JSON at docs/api/v4.0.0.json was already present from the 4.0 prep work — the API site just hadn't been generated against it. Without this, versions.ts listing slug v4-0-0 would have 404'd on the API site since no content directory existed there. The generator output is deterministic from the JSON, so re-running it on the same input produces byte-identical results. Signed-off-by: Peter Amiri <peter@alurium.com>
…e of v4-0-0/ At GA time, the next-snapshot docs are byte-identical to the just-shipped stable docs (modulo the URL slug). As fixes and new features for 4.0.1 land on develop, the two directories diverge. This commit establishes that baseline: - cp -r v4-0-0/ v4-0-1-snapshot/ — full 184-file clone - cp v4-0-0.json v4-0-1-snapshot.json — matching sidebar - find ... sed 's|/v4-0-0/|/v4-0-1-snapshot/|g' — rewrite internal absolute links inside the cloned dir so self-references resolve within the snapshot namespace (relative links untouched — they don't need version segment rewriting) The dropdown entry from versions.ts now resolves to a real, fully- populated tree instead of 404'ing. When the first 4.0.1-era doc change lands, it edits files in v4-0-1-snapshot/ specifically; v4-0-0/ remains the frozen stable docs. Signed-off-by: Peter Amiri <peter@alurium.com>
After renaming the snapshot directory to v4-0-0 and seeding
v4-0-1-snapshot as the new dev clone, sweep the rest of the repo for
references to the retired slug:
- web/content/blog/posts/*.md (6 posts) — outbound URLs to
/v4-0-0-snapshot/... rewritten to /v4-0-0/... so blog links now point
at the stable docs the posts were written against. Redirects in
astro.config.mjs handle anyone hitting the old URLs directly.
- web/sites/guides/src/content/docs/index.md — version list now leads
with v4.0.0 (current), then v4.0.1-SNAPSHOT (dev), with v3 and v2.5
pushed down to archived.
- web/sites/api/src/content/docs/index.md — version table cleaned up:
v4.0.0 promoted to "current release" with 378 functions (matches
generator output from previous commit), v3.0.0 demoted to archived.
- web/sites/guides/src/content/docs/{v2-5-0,v3-0-0}/index.md — "go to
current docs" cross-links now point at /v4-0-0/start-here/installing/
instead of the snapshot URL.
- web/sites/guides/STYLE.md — contributor-facing doc folder reference
now points at v4-0-1-snapshot/ (where new doc PRs land).
- web/packages/ui/src/data/versions.ts (JSDoc example), EditLink.astro
(JSDoc), PageTitle.astro (JSDoc) — example slugs in code comments
refreshed to v4-0-1-snapshot to match what readers see in URLs now.
- web/sites/guides/scripts/verify-docs/verify-docs.mjs — DEFAULT_TARGET
→ src/content/docs/v4-0-1-snapshot (active dev is the right default
for verify-checks).
- web/scripts/visual-regression.mjs — guides canary URL switched to
/v4-0-0/start-here/tutorial/ to match the API site's "canary watches
the stable docs" pattern.
The only file that still mentions v4-0-0-snapshot is astro.config.mjs,
which is intentional — those entries are the redirects that catch
external bookmarks pointing at the old URL.
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 well-structured six-commit post-GA rename: v4-0-0-snapshot → v4-0-0, v4-0-1-snapshot seeding, API site generation, redirects, and a config/reference sweep. The mechanics are sound — DCO, commit lint, and the reference sweep all check out. One correctness issue requires a fix before merge: the v4-0-1-snapshot contributing guide instructs contributors to wire new pages into v4-0-0.json (the now-stable, frozen sidebar) rather than v4-0-1-snapshot.json (the active snapshot sidebar). Requesting changes on that basis.
Correctness
Snapshot contributing guide points at the wrong sidebar file
web/sites/guides/src/content/docs/v4-0-1-snapshot/contributing/writing-docs.mdx was cloned from v4-0-0/contributing/writing-docs.mdx in commit 5 (74f91d7d1), but the version-specific sidebar references were not updated. The file currently contains six stale v4-0-0 references that a contributor following the guide will act on:
line 18: - How to wire your page into `src/sidebars/v4-0-0.json`
line 33: - v4-0-0/ (inside the FileTree)
line 46: - v4-0-0.json (inside the FileTree)
line 162: Edit `web/sites/guides/src/sidebars/v4-0-0.json`
line 164: ```json title="web/sites/guides/src/sidebars/v4-0-0.json"
line 194: 5. **Wire the sidebar.** Add your entry to `src/sidebars/v4-0-0.json`.
web/sites/guides/src/sidebars/v4-0-1-snapshot.json exists and is the correct target — confirmed via ls web/sites/guides/src/sidebars/. A contributor following steps 5 and the "Wire the sidebar" section would add their page to the stable/frozen v4-0-0 sidebar instead of the active snapshot. Once the two sidebars diverge, those misfiled entries will silently appear in the v4.0.0 stable docs and be absent from the snapshot.
The fix is a 6-line substitution in one file. The FileTree should also show v4-0-1-snapshot/ and v4-0-1-snapshot.json as the active targets (the current tree only shows v4-0-0/ with no mention of the snapshot directory, which is confusing for a page that lives in that snapshot).
Suggested fix for web/sites/guides/src/content/docs/v4-0-1-snapshot/contributing/writing-docs.mdx:
- Line 18:
src/sidebars/v4-0-0.json→src/sidebars/v4-0-1-snapshot.json - Lines 33, 46: update FileTree to show
v4-0-1-snapshot//v4-0-1-snapshot.json(or show both beside each other to explain the parallel-tree layout) - Lines 162, 164, 194:
v4-0-0.json→v4-0-1-snapshot.json
Docs
Grammar: broken predicate in writing-docs.mdx site layout paragraph
Both v4-0-0/contributing/writing-docs.mdx and v4-0-1-snapshot/contributing/writing-docs.mdx contain this sentence (line 27 in both files):
The v4.0.0 stable docs are at `v4-0-0/`; the next in-development snapshot is
`v4-0-1-snapshot/` (clone of `v4-0-0/` at GA time, diverges as fixes/features
land) will sit beside it.
The subject ("the next in-development snapshot") has two predicates ("is v4-0-1-snapshot/" and "will sit beside it"), making it ungrammatical. Suggested rewrite:
The v4.0.0 stable docs are at `v4-0-0/`; the next in-development snapshot,
`v4-0-1-snapshot/` (cloned from `v4-0-0/` at GA time, diverges as fixes land),
sits beside it.
This is a minor nit — can be addressed in the same follow-up commit as the sidebar fix.
Commits
Commit 6 subject direction is inverted
chore(web): update outside-doc references to v4-0-0-snapshot for GA
The commit retires references to the old snapshot slug and replaces them with v4-0-0; the body confirms this. The word "to" reads as "adding references pointing at the old URL" rather than "removing them." Commit history is immutable so this is informational only — no action required.
Security, Cross-engine, Tests
Nothing to flag — this PR touches only static Markdown/MDX, JSON, TypeScript, and MJS. No CFML, no framework code, no test surface changed.
What's clean
- All six commits carry
Signed-off-by: Peter Amiri <...>— DCO satisfied. - All commit subjects conform to commitlint:
choretype, unrestricted scopes (web,web/guides,web/api), no ALL-CAPS, all ≤ 100 chars. versions.tsupdate is correct: v4-0-0 promoted tocurrent, v3-0-0 and v2-5-0 demoted toarchived, new v4-0-1-snapshot added assnapshot.sidebarLabelis optional (per the interface's?annotation), so dropping it from the archived entries is fine.astro.config.mjsredirect coverage is honest about the limitation (no full wildcard without CF rules), and the eight explicit entries cover the highest-traffic pages.- v4-0-1-snapshot internal links (
/v4-0-1-snapshot/...) are correct throughout — commit 5 rewrote them properly. - No stray
v4-0-0-snapshotreferences remain outsideastro.config.mjs(where they're intentional redirects). - The PR explicitly scopes what it does not do (no CF wildcard, no content divergence yet, no v3 backport) — good hygiene.
Wheels Bot — Reviewer B (round 1)A's review is accurate and well-evidenced. The main finding — stale sidebar filename references in SycophancyNone detected. A's "What's clean" section cites specific evidence for each clean item rather than offering a blanket LGTM. False positivesNone detected.
Missed issuesNone detected. This PR is static content only (MDX, JSON, TypeScript, MJS) — no CFML, no framework code, no cross-engine surface, no security concerns, no test surface. Verdict alignmentA's CHANGES_REQUESTED is consistent with the findings: the stale sidebar filename is a real bug that would cause contributors to file pages in the frozen stable sidebar instead of the active snapshot one. ConvergenceAligned. A's single required change (update 5 sidebar filename references + FileTree in |
- Fix stale sidebar filename references in v4-0-1-snapshot writing-docs
guide (lines 18, 162, 164, 194): point contributors at
src/sidebars/v4-0-1-snapshot.json (the active snapshot sidebar)
rather than v4-0-0.json (the frozen stable sidebar).
- Update the FileTree in the v4-0-1-snapshot writing-docs guide
(lines 33, 46) to surface both the v4-0-0/ and v4-0-1-snapshot/
content directories alongside both sidebar JSON files, so a
contributor following the guide can see the parallel-tree layout
at a glance.
- Repair the broken predicate on line 27 of both
v4-0-0/contributing/writing-docs.mdx and
v4-0-1-snapshot/contributing/writing-docs.mdx ("the next
in-development snapshot is X will sit beside it" → "the next
in-development snapshot, X, sits beside it").
Doc-only change; no framework code, no tests, no cross-engine surface.
Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Wheels Bot — Address Review (round 1)Applied consensus findings from Reviewer A and Reviewer B's convergence
Skipped (intentionally — A flagged as informational only, not a consensus change): commit 6's inverted "to" subject. Commit history is immutable; the body of that commit is accurate. Doc-only change — no framework code, no tests, no cross-engine surface, so The new commit will trigger a fresh Reviewer A run on the updated SHA. Convergence loop continues until reviewers align on |
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: The new commit (dec472fb2) addresses both actionable findings from round 1 — the six stale v4-0-0.json sidebar references in the snapshot writing-docs guide have been corrected, the FileTree updated to show the parallel-tree layout, and the grammar fix applied to both v4-0-0 and v4-0-1-snapshot versions of the file. No new issues introduced. Approving.
What was fixed (verification)
Sidebar references — all six corrected
web/sites/guides/src/content/docs/v4-0-1-snapshot/contributing/writing-docs.mdx:
| Location | Before | After |
|---|---|---|
| Line 18 (intro bullet) | src/sidebars/v4-0-0.json |
src/sidebars/v4-0-1-snapshot.json |
| Line 162 (section prose) | v4-0-0.json |
v4-0-1-snapshot.json |
| Line 164 (code block title) | v4-0-0.json |
v4-0-1-snapshot.json |
| Line 194 (step 5) | src/sidebars/v4-0-0.json |
src/sidebars/v4-0-1-snapshot.json |
FileTree (lines 33-48): v4-0-0/ is now labeled "(the v4.0.0 stable docs)" without an expanded subtree; v4-0-1-snapshot/ appears beside it labeled "(you are here — the active snapshot)" with its full subtree expanded. The sidebars/ block now lists both v4-0-0.json and v4-0-1-snapshot.json. This is the correct orientation for a contributor editing the snapshot channel.
Grammar — fixed in both files
v4-0-0/contributing/writing-docs.mdx line 27 and v4-0-1-snapshot/contributing/writing-docs.mdx line 27 both now read:
the next in-development snapshot,
v4-0-1-snapshot/(cloned fromv4-0-0/at GA time, diverges as fixes/features land), sits beside it.
The fused subject (is X will sit) is resolved.
Remaining v4-0-0 references in the snapshot file are intentional
Three v4-0-0 mentions survive (grep -n "v4-0-0" output: lines 27, 33, 47). All three name the stable tree for contrast — they are correct contextual references, not stale editorial targets.
Commits
Commit 7 (dec472fb2): docs(web/guides): address Reviewer A/B consensus findings (round 1)
- Type
docs— valid per commitlint allowlist. - Scope
web/guides— unrestricted; appropriate. - Subject ≤ 100 chars, not ALL-CAPS.
Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>matches the commit author — DCO satisfied.- Commit body accurately describes each hunk changed.
Commits 1–6 were verified clean in the previous review (DCO, commitlint, no stale references, correct file counts). Nothing in commit 7 affects that assessment.
Cross-engine, Security, Tests
No change — this is doc-only (MDX only). No CFML, no framework code, no test surface.
Wheels Bot — Reviewer B (round 1)A's review checks out. All six consensus findings from round 1 are verified as implemented; A's citations match the actual diff; the approval is properly evidenced, not a blanket LGTM. Aligned on approve. SycophancyNone detected. A's approval enumerates each fixed line, quotes the before/after text, and confirms remaining False positivesNone detected.
Missed issuesNone detected. Commit 7 touches two MDX files (9 insertions, 7 deletions) and A accounted for every changed line. This is doc-only — no CFML, no framework code, no cross-engine surface, no test surface. Verdict alignmentAPPROVED is consistent with the findings: every actionable item from the round-1 consensus was applied, no new issues were introduced, and the commit metadata is clean. ConvergenceAligned. A and B agree: all consensus changes are in, no outstanding findings, no disputes. Joint recommendation is to approve and merge. |
…version-slug rename The CI run on the previous head of this branch reported: [guides] FAIL — 10,643 pixels differ (threshold: 300) [api] FAIL — 6,167 pixels differ (threshold: 300) Reviewed the diff artifact at: https://github.com/wheels-dev/wheels/actions/runs/25720017511 Confirmed both diffs are entirely confined to the page chrome — the header version-dropdown text ("v4.0.0-SNAPSHOT (dev)" → "v4.0.1-SNAPSHOT (dev)") and the left-sidebar version label ("v3.0.0 (current)" → just "v3.0.0", since v3 is now archived). The page body content is byte- identical on both screenshots; the pixel differences are pure chrome rendering driven by the versions.ts updates already on this branch. Copied the CI-rendered .actual.png files from the visual-regression-diffs artifact directly into web/tests/visual-baselines/, per the comment in .github/workflows/web-deploy.yml that documents this exact procedure ("download the visual-regression-diffs artifact and copy each *.actual.png over the matching web/tests/visual-baselines/*.png, commit, and push"). Using the CI-captured PNGs (not a local refresh) sidesteps the Linux vs macOS font-rendering drift the script's --update mode flags as a caveat. Signed-off-by: Peter Amiri <peter@alurium.com>
|
Visual regression failure was the expected chrome change (version dropdown + sidebar labels driven by versions.ts updates). Downloaded the diff artifact from run 25720017511, confirmed via the diff PNGs that the pixel differences are entirely in header version-switcher text and the left-sidebar version label — page body content is byte-identical. Refreshed baselines using the CI-rendered Also picked up wheels-bot's round-1 fixes ( |
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: Commit 8 (cd8ce3fa8) is the only delta since the round-2 approval (dec472fb2, dismissed when this commit was pushed). It refreshes two binary PNG visual regression baselines (api.png, guides.png) following the procedure documented in .github/workflows/web-deploy.yml lines 204–206. The pixel differences described are confined to page chrome — version-dropdown text and sidebar label — fully consistent with the versions.ts changes already reviewed and approved in rounds 1 and 2. No new correctness, cross-engine, security, or test concerns. Approving.
What's new since round 2
Two binary files changed in commit 8:
| File | Before (bytes) | After (bytes) |
|---|---|---|
web/tests/visual-baselines/api.png |
122,831 | 122,384 |
web/tests/visual-baselines/guides.png |
172,069 | 166,955 |
The commit message documents the reasoning at every step:
- What CI reported — 10,643 px (guides) and 6,167 px (api) against a 300-pixel threshold.
- Verification — diff artifact reviewed at the linked Actions run; diffs confined to the header version-dropdown ("v4.0.0-SNAPSHOT (dev)" → "v4.0.1-SNAPSHOT (dev)") and the sidebar version label ("v3.0.0 (current)" → "v3.0.0", since v3 is now archived).
- Procedure — CI-rendered
.actual.pngfiles copied over the baselines, per the comment at.github/workflows/web-deploy.ymllines 204–206:
# If this job fails on an intentional layout change, download the
# `visual-regression-diffs` artifact and copy each *.actual.png over
# the matching web/tests/visual-baselines/*.png, commit, and push.
- Rationale for CI-captured vs --update mode — avoids Linux vs macOS font-rendering drift that the script's
--updateflag flags as a known caveat.
Commits
chore(web): valid type, unrestricted scope, subject ≤ 100 chars, not ALL-CAPS. Signed-off-by: Peter Amiri <peter@alurium.com> present — DCO satisfied.
Correctness, Cross-engine, Security, Tests
No CFML, no framework code, no test surface — two binary PNGs only. Nothing to flag.
All round-1 findings (stale sidebar references in the snapshot writing-docs guide, grammar in the site-layout paragraph) were addressed in round 2 (dec472fb2). Commit 8 is a clean administrative follow-up with no new review concerns.
Wheels Bot — Reviewer B (round 1)A's review of commit 8 ( SycophancyNone detected. A did not issue a blanket LGTM. The review enumerates: what the two changed binary files are, the pixel-delta figures cited from the CI run, the specific chrome elements that changed (version-dropdown text, sidebar version label), the procedure reference at False positivesNone detected.
Missed issuesNone detected. Commit 8 touches exactly two binary files. There is no CFML code, no framework behavior change, no cross-engine surface, no test surface, and no documentation behavior change. The PNG baselines are test infrastructure artifacts; their refresh is an administrative act following a documented procedure, not a functional change that requires deeper scrutiny. Verdict alignmentA's APPROVED verdict is consistent with the findings: all prior actionable items were resolved in round 2 ( ConvergenceAligned. A and B both agree this commit is a clean administrative follow-up with no outstanding issues. Joint recommendation: approve and merge. |
Pulls in PR #2611 ("wheels packages install" → "wheels packages add" cleanup) plus its companion CHANGELOG entry, _gitignore template fix, plugins/README cleanup, and the new CliTemplateInstallVerbSpec test. Conflict resolution: develop edited five files under v4-0-0-snapshot/ that this branch renamed to v4-0-0/ in commit 4a62207. Git's rename-detection picked the v4-0-1-snapshot/ clone as the move target (content was more similar there since the v4-0-0/ versions had the internal-link sed pass applied in commit 81316ba), so the merge auto-applied develop's content updates to v4-0-1-snapshot/ only. Mirrored those same content updates into v4-0-0/ by hand: copied each merged v4-0-1-snapshot/<path> over the v4-0-0/<path> counterpart and ran `sed 's|/v4-0-1-snapshot/|/v4-0-0/|g'` to restore the stable URL slug. End state: both directories carry develop's content updates, each with the correct URL slug for its channel. Files affected: - command-line-tools/commands/packages/index.mdx - command-line-tools/commands/packages/install.mdx - deployment/observability-and-logging.mdx - start-here/tutorial/03-crud-scaffold.mdx - upgrading/3x-to-4x.mdx Verified post-resolution: v4-0-0/<path> matches v4-0-1-snapshot/<path> modulo URL slugs (diff is purely /v4-0-0/ vs /v4-0-1-snapshot/ tokens). Signed-off-by: Peter Amiri <peter@alurium.com>
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: The sole new delta since round 3 (cd8ce3fa8) is the merge commit 477c2db3e that pulls PR #2611 (packages install → add verb rename) into this branch and manually resolves a five-file conflict caused by develop editing files that were renamed here in commit 4a62207ed. The conflict resolution procedure is documented in the commit message, verifiable, and correct. One documentation nit carries over from PR #2611: the reference page for wheels packages add still lives at the filename install.mdx, so its Astro URL slug resolves to /packages/install/ — ironic for a page whose opening note explains that install is the broken verb. No correctness, security, or cross-engine issues in the merge.
Docs
URL slug of the add reference page still reads install
Both v4-0-0/ and v4-0-1-snapshot/ keep the file named install.mdx even though its title, sidebar label, synopsis, and example were all updated to add:
web/sites/guides/src/content/docs/v4-0-0/command-line-tools/commands/packages/install.mdx
web/sites/guides/src/content/docs/v4-0-1-snapshot/command-line-tools/commands/packages/install.mdx
Astro Starlight derives the page URL from the filesystem path, not the title. With the current filename the URL is:
/v4-0-0/command-line-tools/commands/packages/install/
A user who follows the link in index.mdx (where it is labeled add) lands on a page that immediately warns them not to use install, at a URL whose last segment is install. The index.mdx cross-reference is also technically accurate but semantically jarring — [add](./install) links to a non-add-slug URL.
Two equivalent fixes:
Option A — rename the file (cleaner, no slug override machinery):
git mv ...packages/install.mdx ...packages/add.mdx
Update the link in index.mdx from [add](./install) → [add](./add). Repeat for v4-0-1-snapshot/. No Astro redirect needed since no external URL pointed at /packages/install/ before PR #2611 landed.
Option B — Starlight slug override (keeps the filename, overrides the URL):
---
title: "wheels packages add"
slug: command-line-tools/commands/packages/add # override Astro's path derivation
...
---(Requires the full path from the content root, not just the leaf name; verify against Starlight docs for the correct format.)
This is a nit inherited from PR #2611 — the verb-rename PR updated content but not filenames. Not blocking on its own, but worth a quick follow-up given the user-facing irony.
What is clean in this merge commit
Conflict resolution correctness: Develop's edits to five files were applied to both v4-0-0/ and v4-0-1-snapshot/ with the correct URL slugs. The sed 's|/v4-0-1-snapshot/|/v4-0-0/|g' mirror pass is the right tool for this job, and the commit message documents the process precisely enough to audit.
CliTemplateInstallVerbSpec.cfc (vendor/wheels/tests/specs/packages/): Correctly extends wheels.WheelsTest, uses BDD describe/it syntax (not legacy RocketUnit), and exercises notToInclude/toInclude — both resolved via onMissingMethod in vendor/wheels/wheelstest/system/Expectation.cfc (lines 65-91). No cross-engine issues: ExpandPath, FileExists, FileRead are standard CFML across all engines. No private mixin functions, no client scope, no bracket-notation call hazards.
Content verb corrections: All five conflict-resolved files correctly use wheels packages add in prose (03-crud-scaffold.mdx line 287, upgrading/3x-to-4x.mdx lines 248 and 298). No stale wheels packages install <name> command invocations remain in user-facing steps.
Merge commit hygiene: Signed-off-by: Peter Amiri <peter@alurium.com> present — DCO satisfied. Merge commits are not required to follow conventional-commit format.
Non-CFML scope: The entire merge delta is MDX, JSON, Markdown, and one CFC test. No framework CFML, no model/controller/view/migration surface.
Wheels Bot — Reviewer B (round 1)A's review is accurate and well-evidenced for what is a merge commit pulling in PR #2611's verb rename. The single finding — SycophancyNone detected. A's "What is clean" section cites specific file paths, line numbers, method names, and the procedure reference in False positivesNone detected.
Missed issuesNone detected. This merge commit touches MDX, Markdown, a CHANGELOG entry, two template files, and one CFC test. No framework CFML, no model/controller/view/migration surface, no security surface, no cross-engine concerns. Verdict alignmentA's COMMENTED verdict is consistent with the findings: the only issue is a non-blocking slug/filename mismatch inherited from PR #2611, and A provides two concrete fix paths for a follow-up. Framing it as advisory rather than blocking is the right call given the issue predates this PR's scope. ConvergenceAligned. A and B agree: the merge commit is clean, the sole advisory finding is real but non-blocking, and the PR's core work (GA rename, snapshot seeding, API generation, outside-doc sweep, conflict resolution) is correct throughout. Joint recommendation is to approve and merge; rename |
1 participant
Summary
Post-GA docs reorganization for the v4.0.0 release that shipped today:
v4-0-0-snapshot→v4-0-0to reflect the now-stable channel status.v4-0-1-snapshot/as a clone-and-diverge baseline ofv4-0-0/so the next-snapshot dropdown entry resolves to a real tree.docs/api/v4.0.0.json(the JSON has been ready since the GA prep — the generator just hadn't been run against it).web/packages/ui/src/data/versions.ts) — promote v4-0-0 tocurrent, demote v3-0-0 toarchived, add v4-0-1-snapshot as the newsnapshot./v4-0-0-snapshot/landing pages so external bookmarks/SEO equity transfer to the new slug.Commits (logically separable for review)
4a62207edchore(web/guides): rename v4-0-0-snapshot dir to v4-0-0 for GA81316bab8chore(web/guides): rewrite internal /v4-0-0-snapshot/ links in renamed dir to /v4-0-0/c1bfe90cdchore(web): update versions.ts + astro redirects for v4.0.0 GAdcaa5a6d5chore(web/api): generate v4.0.0 API content from docs/api/v4.0.0.json74f91d7d1chore(web/guides): seed v4-0-1-snapshot/ as clone-and-diverge baseline of v4-0-0/7ca37c693chore(web): update outside-doc references to v4-0-0-snapshot for GAEach is reviewable independently; the rename in commit 1 is
git mvso history is preserved.Diff shape
docs/api/v4.0.0.json(commit 4).versions.ts(1 source-of-truth update) +astro.config.mjs(redirects).Pre-flight checks performed
find v4-0-0/andv4-0-1-snapshot/both report 184 files (clone is complete)find api/v4-0-0/reports 387 files (generator output matches its own "Generated 378 function pages across 9 sections" message + 9 section index.md files)v4-0-0//v4-0-0-snapshot/references insidev4-0-0/(the only intentional remaining mentions are the redirects inastro.config.mjs)Signed-off-by: Peter Amiri <peter@alurium.com>Astro build verification was deferred to CI — the worktree doesn't have a fresh
pnpm install, and CI will run the canonical build against the merged tree anyway.What this does NOT do
redirectsmap can't catch-all withoutgetStaticPaths, so arbitrary deep links to/v4-0-0-snapshot/foo/barwill 404. The explicit redirects inastro.config.mjscover the URLs most likely to be linked externally (root, installing, tutorial, first-15-minutes, release-channels, cfml-engines, command-line-tools/installation, cli-reference). If SEO retention from deep-link backlinks matters, a CF rule mapping/v4-0-0-snapshot/*→/v4-0-0/$1would close the gap — not in scope for this PR.Test plan
web/sites/guidesandweb/sites/api/v4-0-0/start-here/installing/resolves and renders/v4-0-1-snapshot/start-here/installing/resolves and renders (should be identical to v4-0-0 at this commit)/v4-0-0-snapshot/redirects to/v4-0-0//v4-0-0/renders the new function index