docs: drop Chocolatey path, switch to Scoop; banner v2/v3 as historical#2559
docs: drop Chocolatey path, switch to Scoop; banner v2/v3 as historical#2559
Conversation
v4 docs: the Windows install section in installing.mdx and installation.mdx had been pointing at a non-existent v2.x LuCLI Chocolatey package that was never going to ship. Replace with the real path now that the Scoop bucket is live at wheels-dev/scoop-wheels (PR #2552 + the live bucket repo). Includes the channel-switch flow and a forward-pointer to release-channels. v2-5-0 and v3-0-0 index pages: add a Starlight :::caution::: banner clarifying these docs are historical and that CommandBox-based references are accurate for those versions but no longer reflect current install paths. Doesn't touch the body content — those refs are correct in context, just outdated for new projects. Closes the "older version pages still mention CommandBox" cleanup from the master plan.
![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: The PR's core intent is solid — the main Windows install section in both installation.mdx and installing.mdx is correctly rewritten for Scoop, and the v2/v3 historical banners are accurate and well-worded. However, the edit is incomplete: four Chocolatey references remain in the two edited files, one of which actively misdirects Windows users to a manual download path instead of scoop update wheels. Requesting changes on that correctness issue; the rest are docs consistency nits that should be fixed in the same pass.
Correctness
installing.mdx line 209 — Windows upgrade tab still references the removed Chocolatey path
After this PR, Windows users install via Scoop. But the Upgrading section's Windows tab was not updated:
Until the v2 Chocolatey package ships, upgrade by re-downloading the
launcher and module from GitHub Releases:
This is the wrong upgrade path. Scoop users should run scoop update wheels (or scoop update wheels-be). The current text sends Windows users down the old manual-download path and references a Chocolatey package that is no longer the intended distribution channel. Suggested replacement for the Windows upgrade tab:
scoop update wheels
# or, for the bleeding-edge channel:
scoop update wheels-beThe two manual-download steps below that line (re-extract zip, etc.) should be removed or moved under the Manual JAR install section if they still apply.
Docs
installation.mdx line 3 — frontmatter description still says Chocolatey
description: Install the wheels binary via Homebrew, Chocolatey, or a manual JAR download, and verify your setup.The section heading changed to ## Windows (Scoop); the description should follow:
description: Install the wheels binary via Homebrew, Scoop (Windows), or a manual JAR download, and verify your setup.installation.mdx line 11 — intro paragraph lists Chocolatey as the Windows channel
The `wheels` binary is distributed through three channels: Homebrew for macOS
and Linux, Chocolatey for Windows, and a direct JAR download...
Should read "Scoop for Windows".
installation.mdx line 22 — Requirements section still names Chocolatey
If you're installing manually — or on Windows outside the Chocolatey package —
grab a JDK 21 build from Adoptium
Scoop handles java/openjdk21 as an automatic dependency; the parenthetical can now read "or on Windows without Scoop".
Out-of-scope (not blocking, follow-up welcome)
Several other v4 docs files have stale LinkCard description fields still reading "Homebrew, Chocolatey, manual" — they point at the Installation page but are not in scope for this PR. A follow-up pass would clean up:
command-line-tools/configuration.mdx:251command-line-tools/mcp-integration.mdx:114command-line-tools/index.mdx:34command-line-tools/core-commands/modules-and-deps.mdx:318
Commits
docs: drop Chocolatey path, switch to Scoop; banner v2/v3 as historical — valid type (docs), no scope (acceptable), subject within 100 chars, not ALL-CAPS. Passes commitlint.
Wheels Bot — Reviewer B (round 1)A's review is accurate and well-targeted. The four remaining Chocolatey references are all real (verified against current HEAD), the upgrade tab misdirection is the most consequential of them, and the verdict (request-changes) is proportionate. No sycophancy, no false positives. One minor observation below that does not change the alignment. SycophancyNone detected. A's "core intent is solid" framing correctly precedes a request-changes verdict — it is accurate context-setting, not rubber-stamping. False positivesNone detected. I checked each of A's four cited locations against the current file state:
Missed issuesOne minor item A did not flag: the PR's own test plan has the Astro/Starlight build unchecked ( Not a blocking concern; CI is the gatekeeper. It does not change the request-changes recommendation. Verdict alignmentA's CHANGES_REQUESTED verdict is consistent with the findings. The upgrade tab actively misdirects Scoop users toward a manual download flow that no longer applies — a correctness defect, not a nit. ConvergenceAligned. A correctly identified all the incomplete edits, all findings are verified against current HEAD, and the request-changes verdict is appropriate. Emitting converged-changes so bot-address-review can apply the consensus. The four changes to apply:
|
- installation.mdx frontmatter description: Chocolatey → Scoop (Windows) - installation.mdx intro paragraph: Chocolatey for Windows → Scoop for Windows - installation.mdx Requirements parenthetical: outside the Chocolatey package → without Scoop - installing.mdx Windows upgrade tab: replace manual re-download steps with `scoop update wheels` / `scoop update wheels-be`
Wheels Bot — Address Review (round 1)Applied consensus findings from Reviewer A and Reviewer B's convergence (round 1):
The two remaining "Chocolatey" mentions in the edited files ( Reviewer B's minor observation about the Astro/Starlight build was not actionable here (it's a CI gate, not a content change). This is a docs-only PR, so no test runner was invoked. The new commit will trigger a fresh Reviewer A run on the updated SHA. Convergence loop continues until reviewers align on `approve` or the outer-loop cap (5 rounds) is reached. |
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: Round 1 re-review. All four issues raised in the previous review have been correctly addressed in commit 983db490d. The docs-only change is now accurate and internally consistent across all four files. No correctness, cross-engine, or security concerns remain. Approving.
Round-1 findings — resolved
| Finding | Status |
|---|---|
installation.mdx frontmatter description still named Chocolatey |
Fixed: Scoop (Windows) |
installation.mdx intro paragraph listed Chocolatey as the Windows channel |
Fixed: Scoop for Windows |
installation.mdx Requirements parenthetical named Chocolatey |
Fixed: without Scoop |
installing.mdx Windows upgrade tab still sent users down the manual re-download path |
Fixed: scoop update wheels / scoop update wheels-be |
Docs
One optional nit, not blocking:
installation.mdx lines 56–64 — Scoop install block has no title attribute
Every other code block in the file carries a title= (e.g. title="illustrative — Homebrew install", title="PowerShell"). The new Scoop block is missing one:
scoop bucket add wheels https://github.com/wheels-dev/scoop-wheels
...Consider adding title="PowerShell" for consistency with the rest of the file. Non-blocking.
Commits
docs: drop Chocolatey path, switch to Scoop; banner v2/v3 as historical— valid type, no scope, subject within 100 chars. Passes commitlint.docs: address Reviewer A/B consensus findings (round 1)— valid type, no scope, subject within 100 chars. Passes commitlint.
Wheels Bot — Reviewer B (round 1)A's review is accurate and the approve verdict is well-founded. All four prior findings are verified against the current diff. One minor extension to A's own nit below, which does not change the alignment. SycophancyNone detected. A's approval is backed by a findings-resolution table with specific line-level verification. False positivesNone detected. I re-read the cited diff sections for all four resolved findings:
A's nit (missing Missed issuesOne minor item, same category as A's own nit:
A flagged the first code block in the new Windows (Scoop) section (the install block) as missing a scoop uninstall wheels && scoop install wheels-be
scoop uninstall wheels-be && scoop install wheelsOther code blocks in the same file consistently carry Verdict alignmentA's APPROVED verdict is consistent with the findings. The original correctness defects are all resolved, and the only outstanding item is a style nit the author can address as a follow-up. ConvergenceAligned on approve. A correctly identified all four fixed issues, verified them against the current file state, and the approval is appropriate for a docs-only cleanup with no correctness, security, or cross-engine concerns. The two untitled code blocks in |
* ci: retry blog visual baseline auto-push with fetch+rebase loop The "Commit pre-refreshed blog baseline" step in web-deploy.yml's visual-regression job pushed to develop with a single `git push origin HEAD:develop` — no retry. When develop moved during the ~3 min job runtime (e.g., another PR merging right behind a blog content push), the push was rejected with `! [rejected] HEAD -> develop (fetch first)` and the auto-refreshed baseline was silently dropped. Effect: every subsequent non-blog PR tripped visual-regression on a stale baseline until someone manually refreshed. Concrete trigger this week: PRs #2549 + #2551 merging back-to-back left blog.png predating both "Background Jobs Without Redis" and "Multi-Tenancy Built In" posts, blocking PR #2559 with 38,581-pixel diff. Fix: wrap the push in a 5-attempt fetch+rebase+push loop. Rebase conflict path exits clean (would only happen if a parallel run already refreshed the baseline, making ours redundant). Push-rejected path retries with a short randomized backoff. See run 25647803649 for the failure mode. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * ci: refresh stale blog baseline and address review nits Two pieces, both fallout from the race-condition bug this PR fixes: 1. Refresh `web/tests/visual-baselines/blog.png`. The May 9 → present auto-refresh pushes were dropped by the bug, so develop's baseline predates `Background Jobs Without Redis` and `Multi-Tenancy Built In` posts. Without this commit, PR #2560's own visual-regression check stays red and every non-blog PR keeps tripping. Regenerated locally via `pnpm --filter @wheels-dev/site-blog build` + `node scripts/visual-regression.mjs --update --site blog`; verified the freshly-written baseline passes a subsequent check run with 0-pixel diff. 2. Two minor nits from Reviewer A on the retry loop: - Guard the final-iteration `sleep` behind `[ "$attempt" -lt 5 ]` so the 5th rejected push doesn't sleep 2-6s before exiting. - Add `|| true` to `git rebase --abort` so a failed abort (e.g., already-clean rebase state) doesn't flip the intended exit-0 conflict path to exit-1 under `set -euo pipefail`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * ci: don't print misleading "will retry" message on final attempt Reviewer B noted that the "Push rejected on attempt $attempt; will fetch + rebase + retry." echo runs unconditionally inside the for-loop body, so on attempt 5 it lies — there's no retry coming, the loop falls through to exit 1. Move the echo inside the same `[ "$attempt" -lt 5 ]` guard that already skips the backoff sleep, and emit a distinct "final attempt, no retry" message in the else branch. Pure cosmetic; no control-flow change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 participant
Summary
Two parallel cleanups from the master plan:
v4 docs: the Windows install section in
installing.mdxandinstallation.mdxhad been pointing at a non-existent v2.x LuCLI Chocolatey package that was never going to ship. Replace with the real path now that the Scoop bucket is live atwheels-dev/scoop-wheels. Includes the channel-switch flow and a forward-pointer to the Release Channels page.v2-5-0 + v3-0-0 index pages: add a Starlight
:::caution:::banner clarifying these docs are historical and that CommandBox-based references are accurate for those versions but no longer reflect current install paths. Banner only — does NOT touch the body content. Those refs are correct in context (v2/v3 used CommandBox); the banner just steers new users toward v4.Files changed
web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/installation.mdxweb/sites/guides/src/content/docs/v4-0-0-snapshot/start-here/installing.mdxweb/sites/guides/src/content/docs/v2-5-0/index.mdweb/sites/guides/src/content/docs/v3-0-0/index.mdWhat I deliberately did NOT change
wheels modules/wheels depsForgeBox mentions — ForgeBox is still a supported dep sourceTest plan