docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_*#2777
Conversation
…be_* PR #2759 (2026-05-18) renamed the snapshot Linux artifacts from `wheels_*` to `wheels-be_*` (debs) and `wheels-be-*.x86_64.rpm` (rpms) so the package name itself differentiates the channel. The install guides were not updated alongside that rename, so every documented `curl -fsSLO ...` command for Linux bleeding-edge install resolves to a 404 against the actual snapshot release assets. Verified against v4.0.2-snapshot.1923 (published 2026-05-20): Guide says: .../wheels_4.0.2.snapshot.1923_amd64.deb → 404 Actual asset: .../wheels-be_4.0.2.snapshot.1923_amd64.deb Fix all six pages where the snippets / prose examples appear (three unique pages mirrored across v4-0-0 and v4-0-1-snapshot doc versions): start-here/installing.mdx — "Want bleeding-edge?" aside start-here/release-channels.mdx — main BE install snippets + "Switching channels" snippets + tilde-mangling prose command-line-tools/installation.mdx — bleeding-edge install snippets The substitutions are scoped to bleeding-edge contexts (snippets using `${SNAP_FILENAME_VER}` and prose `wheels_4.0.0.snapshot.*` filename examples). Stable-channel snippets, which use `${WHEELS_VERSION}` and fetch from `wheels-dev/wheels` (not `wheels-snapshots`), are unchanged — they correctly retain the bare `wheels_` / `wheels-` prefixes because the stable package name on Linux is still just `wheels`. Without this fix, users cannot install or test bleeding-edge / develop snapshots on Linux via the documented flow. This blocks user-side verification of develop-only fixes before they ship in the next stable patch — including PR #2776 (Linux .deb framework nesting fix) and PR #2774 (defensive onError guard), both of which close issue #2773. Signed-off-by: Peter Amiri <peter@alurium.com>
![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 PR fixes the right problem — the bleeding-edge Linux package was renamed wheels-be_* by #2759 and the guides weren't updated — but the fix is incomplete. Two bleeding-edge install snippets in both release-channels.mdx files (inside the Linux Tabs component) were missed and still resolve to 404. The PR's own verification sweep failed to catch them because they use a different bash variable name (WHEELS_FILENAME_VER) than the grep checked (SNAP_FILENAME_VER). Requesting changes to close those two remaining gaps before merge.
Correctness
Missed bleeding-edge snippets in release-channels.mdx — both doc versions
web/sites/guides/src/content/docs/v4-0-0/start-here/release-channels.mdx, lines 104–105 and 112:
# Line 104–105 (Debian / Ubuntu (bleeding-edge) tab)
curl -fsSLO "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${WHEELS_TAG}/wheels_${WHEELS_FILENAME_VER}_amd64.deb"
sudo apt install "./wheels_${WHEELS_FILENAME_VER}_amd64.deb"
# Line 112 (Fedora / RHEL (bleeding-edge) tab)
sudo dnf install "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${WHEELS_TAG}/wheels-${WHEELS_FILENAME_VER}.x86_64.rpm"The same stale content appears at the identical line numbers in v4-0-1-snapshot/start-here/release-channels.mdx. These code blocks are titled "Debian / Ubuntu (bleeding-edge)" and "Fedora / RHEL (bleeding-edge)" — they fetch from wheels-dev/wheels-snapshots and need the wheels-be_ / wheels-be- prefix, yet the PR's diff leaves them untouched.
The root cause of the miss: the PR's verification sweep in the checklist checked for patterns containing ${SNAP_FILENAME_VER}, but these snippets bind the tag to WHEELS_FILENAME_VER (a different variable name). A user copying the code from the Linux tab would get a 404, defeating the fix's stated goal of letting users verify develop-only fixes on Linux.
Fix needed in both v4-0-0 and v4-0-1-snapshot:
# Debian / Ubuntu (bleeding-edge)
curl -fsSLO "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${WHEELS_TAG}/wheels-be_${WHEELS_FILENAME_VER}_amd64.deb"
sudo apt install "./wheels-be_${WHEELS_FILENAME_VER}_amd64.deb"
# Fedora / RHEL (bleeding-edge)
sudo dnf install "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${WHEELS_TAG}/wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpm"Docs
Stale prose on Linux channel naming — release-channels.mdx line 129 (both versions)
On **Linux**, only a single package name (`wheels`) is published per channel today; the channel distinction lives in the source repo
Since #2759 renamed the bleeding-edge artifact to wheels-be, this is no longer accurate — Linux now ships two differently-named packages, just like macOS/Windows. The macOS/Windows paragraph immediately above (line 127) already says "two differently-named packages (wheels vs wheels-be)". The Linux paragraph needs the same update. Suggested wording:
On Linux, two package names are published:
wheels(stable, fromwheels-dev/wheels) andwheels-be(bleeding-edge, fromwheels-dev/wheels-snapshots). Because they are different package names,apt/dnfdoes not treat the install as an in-place upgrade — see the snippets below.
What looks good
The changes that are present are correct and symmetric across v4-0-0 and v4-0-1-snapshot:
- "Switching channels" snippets updated to
wheels-be_/wheels-be-in all four shells. - "Want bleeding-edge?" Aside in
installing.mdxupdated consistently. - Tilde-mangling Aside caution in
release-channels.mdxupdated. command-line-tools/installation.mdxillustrative snippets updated.- Stable-channel snippets (
wheels_${WHEELS_VERSION}fromwheels-dev/wheels) correctly untouched.
Commits
Single commit docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_* — valid type, descriptive subject, within 100 chars, DCO sign-off present. No issues.
Wheels Bot — Reviewer B (round 1)A's review is solid. Both findings are verified against the actual files. The SycophancyNone detected. A itemized concrete file locations and line numbers, provided suggested replacements, and correctly resisted approving a doc PR with live 404 snippets. False positivesNone detected.
Missed issuesOne additional issue A did not flag:
Verdict alignmentA's ConvergenceNot aligned yet. A's findings are verified and the |
There was a problem hiding this comment.
Wheels Bot — Reviewer A response (round 1)
B's critique is correct on the missed issue: my proposed prose fix for line 129 ("Because they are different package names, apt/dnf does not treat the install as an in-place upgrade") directly contradicts the inline comment at lines 142-143 of the Switching channels snippet ("apt sees a newer version... and upgrades in place — no uninstall step needed."), and I failed to flag that existing comment when reviewing. I concede that finding. My two original findings from the initial review stand — B independently verified both. Verdict remains request-changes, now covering three related items.
Conceded points
- Lines 142-143 (both
release-channels.mdxversions) — stale "upgrades in place" comment inconsistent with A's line 129 prose suggestion: B is correct. The "upgrades in place" comment was accurate when both channels published a package namedwheels— same name means apt automatically treats the new install as an upgrade. With the PR's rename towheels-be, apt now sees a different package name and would installwheels-beas a separate, new package alongsidewheels(with two competing/usr/bin/wheelsbinaries) unless the.debdeclaresReplaces: wheelsandConflicts: wheelsin its metadata. I should have flagged lines 142-143 as a related site requiring resolution, and I should not have proposed prose for line 129 that presupposes the answer without checking the package metadata. B caught the gap.
Defended points
- Lines 104-105 and 112 (both doc versions) — primary install Tabs still use
wheels_prefix: Confirmed in the current files; the diff did not touch those lines. Still broken. - Line 129 (both doc versions) — "only a single package name (
wheels)" prose is stale: Confirmed in the current files — this line is unchanged and now factually wrong after the rename. Still needs updating.
Updated verdict
Still request-changes: the PR needs three items resolved. (1) Lines 104-105 and 112 in both doc versions — update to wheels-be_ / wheels-be- prefix. (2) Lines 142-143 and line 129 must be made consistent: the PR author should confirm whether the wheels-be .deb/.rpm declares Replaces: wheels and Conflicts: wheels in its package metadata — if yes, the "upgrades in place" comment at lines 142-143 is still accurate and line 129 should be updated to explain that apt/dnf handles the channel switch via package replacement metadata; if no, lines 142-143 need to drop the "no uninstall step needed" claim and the snippet needs an explicit apt remove wheels step before installing wheels-be. Either way, the two locations must agree.
…eels-be-install-snippets
…ux switching semantics Round-1 reviewer findings on PR #2777: A's Nit 1 — primary install Tabs at lines 104-105 (Debian/Ubuntu BE) and 112 (Fedora/RHEL BE) of `release-channels.mdx` still resolved to 404. My initial verification sweep grep'd for `${SNAP_FILENAME_VER}`, but these snippets bind the tag to `${WHEELS_FILENAME_VER}` (a different bash var name). The fix is the same — point at the `wheels-be_` / `wheels-be-` artifacts. A's Nit 2 + B's catch — the "Switching channels" section had three related staleness bugs after #2759 renamed the BE package: 1. Line 129 prose claimed "only a single package name (`wheels`) is published per channel today" — false post-rename. 2. Lines 142-143 inline comment ("upgrades in place — no uninstall step needed") was true when both channels shared the `wheels` name, but the new world depends on the actual nfpm-declared `Replaces:` / `Conflicts:` metadata. B caught the contradiction between A's proposed line-129 prose and the existing line-142 comment. 3. Lines 158-172 (Linux BE → stable, both Debian and Fedora) had the *same* conceptual bug as 142-143: they prescribed `--allow-downgrades` (apt) / `dnf downgrade`, both of which assume same-package-name version transitions. With different names, both would fail with a `/usr/bin/wheels` file conflict because the stable `wheels` package doesn't declare `Replaces:`/`Obsoletes: wheels-be`. Reviewers didn't explicitly flag this set, but it's the same root cause and listing them inconsistently would have left readers worse off. Verified the actual nfpm metadata before rewriting (so the prose matches what the packages really declare): wheels-be deb: Replaces: wheels + Conflicts: wheels wheels-be rpm: Conflicts: wheels (no Obsoletes) wheels deb: no Replaces/Conflicts against wheels-be wheels rpm: no Conflicts/Obsoletes against wheels-be The new prose at line 129 explains the asymmetry up front; each snippet now carries a short comment naming the specific metadata that drives its action (or the lack of metadata that requires the explicit `apt remove` / `dnf remove`). Stable-channel snippets and stable install Tabs are unchanged. Signed-off-by: Peter Amiri <peter@alurium.com>
All round-1 findings addressed in Acknowledgments first: A and B are both right that my round-0 verification sweep was too narrow — I grep'd for Changes pushed
Beyond the explicit findings (scope addition flagged here, not a surprise)Lines 158-172 (Linux bleeding-edge → stable for both Debian and Fedora) had the same conceptual bug as 142-143 and were inconsistent with whatever resolution we chose there:
I made these changes even though the reviewers didn't explicitly flag them, on the principle B used for line 142-143: "the two locations must agree." Listing one direction with Verification on this pushSkippedNothing — every flagged item addressed. Convergence-on-approve from reviewers welcome whenever they've re-read the diff. |
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: This follow-up commit fully resolves all three items from the previous request-changes round — the two missed bleeding-edge install snippets in both release-channels.mdx versions (the WHEELS_FILENAME_VER tabs that were not caught by the initial grep), the stale line-129 prose, and the contradictory line-142/143 comment. The package-metadata-driven rewrite of the Switching channels section is accurate and internally consistent. One minor doc nit on comment accuracy, but nothing that should block merge.
Correctness
All three prior findings addressed:
-
Lines 104–105 and 112 (both doc versions) — primary install Tabs with
WHEELS_FILENAME_VER: Fixed. Both versions now readwheels-be_${WHEELS_FILENAME_VER}_amd64.deb/wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpm. -
Line 129 prose (both doc versions): Fixed. The old "only a single package name (
wheels) is published per channel today" claim is replaced with an accurate description of the asymmetricReplaces:/Conflicts:/Obsoletes:metadata, explaining up front why the stable→BE swap on Debian is automatic while the Fedora direction and both reverse directions need explicit removes. -
Lines 142–143 "upgrades in place" comment (both doc versions): Fixed. The comment now accurately cites
Replaces: wheels + Conflicts: wheelsas the mechanism.
The four Linux switching snippets are now consistent with the line-129 prose and with each other.
Minor nit — line 164–165 (both doc versions), "bleeding-edge → stable (Debian / Ubuntu)" comment:
# The stable wheels .deb does not declare Replaces: wheels-be, so apt
# would fail with a /usr/bin/wheels file conflict. Remove wheels-be
# first.The real failure mode is the package-level Conflicts: wheels already declared by wheels-be — apt would refuse to install wheels while wheels-be is present with a package conflict error, not a dpkg-level file-ownership conflict. The prescription (apt remove wheels-be first) is correct regardless, and an advanced user debugging the error message might be confused by the "file conflict" framing. Suggested wording:
# wheels-be declares Conflicts: wheels, so apt refuses to install wheels
# while wheels-be is present. Remove wheels-be first.This is a nit — does not block merge.
What looks good
- Symmetric across
v4-0-0andv4-0-1-snapshot: all six files updated identically. - Stable-channel snippets (
${WHEELS_VERSION}fromwheels-dev/wheels) correctly untouched in both doc versions. - Removed
--allow-downgradesanddnf downgradefrom the reverse-direction snippets; replacing them with explicit remove-then-install is the correct approach when two differently-named packages share a binary path. - No other doc versions (
v2-5-0,v3-0-0) contain Linux snapshot install snippets — confirmed from directory listing.
Commits
78f2910ea docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_*— valid type, subject within 100 chars, DCO sign-off present.c4287ab10 Merge remote-tracking branch ...— merge commit, no commitlint requirement.c36bef6b5 docs(web/guides): fix release-channels.mdx — missed BE Tab URLs + Linux switching semantics— valid type, subject within 100 chars, DCO sign-off present. Commit body explains the why (missedWHEELS_FILENAME_VERvariable, nfpm metadata verification before rewriting switching prose).
…comments Reviewer A round-2 nit on PR #2777: the BE → stable (Debian) snippet's comment said apt "would fail with a /usr/bin/wheels file conflict", framing the failure mode as a dpkg-level file-ownership conflict. The actual blocker is the package-level `Conflicts: wheels` declaration in wheels-be's deb metadata — apt refuses the install with a package conflict error before dpkg ever attempts to unpack files. An advanced user debugging the actual error message would be confused by the file-conflict framing. Rewrite the Debian comment per A's suggestion, naming the actual mechanism: `wheels-be declares Conflicts: wheels`. Kept the secondary note about the missing `Replaces: wheels-be` in stable since it explains why apt also wouldn't auto-remove (relevant context if a reader wonders whether a single command could swap them). Updated the Fedora BE → stable comment to use parallel framing for consistency — same root cause (`wheels-be` declares `Conflicts: wheels`, applies bidirectionally on rpm too). Reviewer A only flagged the Debian site explicitly, but leaving the two comments inconsistent would have invited the same "two sites must agree" finding that caught round 1's line-142 / line-129 contradiction. Signed-off-by: Peter Amiri <peter@alurium.com>
Wheels Bot — Reviewer B (round 1)A's review of the follow-up commit is accurate and well-grounded. All three prior request-changes items are verifiably fixed in the diff. There is one concrete actionable nit — A identified it correctly but called it non-blocking. B concurs on the diagnosis but recommends applying it before merge, since the comment misleads users about the actual apt failure mechanism. Converging on changes for that one-line fix in two files. SycophancyNone detected. A used False positivesNone detected.
Missed issuesNone detected. The PR author's proactive fix to the bleeding-edge → stable snippets (lines 158–172, dropping Verdict alignmentA's ConvergenceAligned. A identified the lines-164–165 comment inaccuracy with a concrete suggested replacement; B agrees it is real and actionable (a two-line change in two mirrored files). The fix is clear: replace the "file conflict" framing with A's suggested wording that names the |
Addressed in
No other staleness from this comment-accuracy class — verified via |
Already addressed in # wheels-be declares Conflicts: wheels, so apt refuses to install wheels
# while wheels-be is present. (Stable wheels .deb also doesn't declare
# Replaces: wheels-be, so apt wouldn't auto-remove either way.) Remove
# wheels-be first.The Fedora comment got the same parallel framing — your "two sites must agree" principle applies here exactly as it did to round 1's line-142 / line-129 split, so I extended A's Debian-only suggestion to the rpm site as well. Verified via PR should be at |
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: The final commit (c73fe81) directly and correctly resolves the round-2 nit — the BE→stable (Debian/Ubuntu) comment now names wheels-be declares Conflicts: wheels as the actual blocking mechanism rather than a dpkg file-ownership conflict, and the Fedora comment is updated in parallel for consistency. All three round-1 findings and the round-2 nit are now addressed. The PR is ready to merge.
Correctness
All outstanding items from prior rounds are closed:
-
Lines 104–105 and 112 (both doc versions) —
WHEELS_FILENAME_VERsnippets: Fixed in c36bef6. Both doc versions now emitwheels-be_${WHEELS_FILENAME_VER}_amd64.deb/wheels-be-${WHEELS_FILENAME_VER}.x86_64.rpmcorrectly. -
Line-129 Linux channel-naming prose (both doc versions): Fixed in c36bef6. The stale "only a single package name" claim is replaced with an accurate description of the package metadata asymmetry (
Replaces:+Conflicts:on Debian,Conflicts:only on Fedora). -
Lines 142–143 "upgrades in place" comment (both doc versions): Fixed in c36bef6. The comment now cites the actual
Replaces: wheels + Conflicts: wheelsmetadata as the mechanism. -
Round-2 nit — BE→stable (Debian) comment framing (both doc versions): Fixed in c73fe81. The comment now reads:
# wheels-be declares Conflicts: wheels, so apt refuses to install wheels # while wheels-be is present. (Stable wheels .deb also doesn't declare # Replaces: wheels-be, so apt wouldn't auto-remove either way.) Remove # wheels-be first.
This correctly names the package-level
Conflicts:declaration as the blocker (apt refuses before dpkg attempts file unpacking), rather than the previously misleading "file conflict" framing. The secondary note about missingReplaces: wheels-bein stable is accurate and useful — it answers the natural follow-up question of why a single command cannot swap them automatically.The Fedora BE→stable comment was updated with parallel framing as a proactive consistency fix, which is the right call given that the prior round-1 review caught the line-129 / line-142 consistency gap.
The four Linux switching snippets, the line-129 prose, the tilde-mangling Aside, and the comment text are now internally consistent in both doc versions.
Commits
All four PR commits conform to commitlint:
78f2910ea docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_*— valid type, DCO present.c4287ab10 Merge remote-tracking branch ...— merge commit, no commitlint requirement.c36bef6b5 docs(web/guides): fix release-channels.mdx — missed BE Tab URLs + Linux switching semantics— valid type, subject within 100 chars, DCO present.c73fe8181 docs(web/guides): name the actual Conflicts declaration in BE→stable comments— valid type, subject within 100 chars, DCO present. Commit body explains why the file-conflict framing was wrong and why the Fedora comment was updated proactively.
What looks good (overall)
- Symmetric across
v4-0-0andv4-0-1-snapshotthroughout. - Stable-channel snippets (
wheels_${WHEELS_VERSION}) correctly untouched. - Removed
--allow-downgradesanddnf downgradein favor of explicit remove-then-install, which is the correct approach when two differently-named packages compete for/usr/bin/wheels. - The PR description's scope clarification (Phase 2 apt/yum repos, stable snippets, Brew/Scoop) correctly bounds what is and is not changed.
Wheels Bot — Address Review (round 1)Consensus findings from Reviewer A and Reviewer B's convergence at Consensus finding (from B's
Verification on current head
Reviewer A has already submitted an APPROVED review on Skipped:
|
Wheels Bot — Reviewer B (round 1)A's review of the final commit is clean and well-grounded. All four prior findings are verifiably addressed in the diff. No sycophancy, no false positives, no missed issues. A's APPROVED verdict is correct. Converging on approve. SycophancyNone detected. A itemized each round-1 and round-2 item with specific commit hashes, quoted fix text, and line-level citations rather than an unsupported LGTM. The PR touches no security, migration, deploy, or DI subsystems — docs-only approval requires no human gate. False positivesNone detected. Verified each of A's four claims against the actual diff:
Missed issuesNone detected. Verified independently:
Verdict alignmentA's APPROVED state is consistent with all prior ConvergenceAligned on approve. Every finding across all three rounds has been addressed, the diff is internally consistent across both doc versions, and the final commit correctly names the |
1 participant
Summary
PR #2759 (2026-05-18) renamed the snapshot Linux artifacts to use a
wheels-beprefix so the package name itself differentiates the bleeding-edge channel from stable onapt/dnf. The install guides weren't updated alongside that rename, so every documentedcurl -fsSLOcommand for Linux bleeding-edge install resolves to a 404 against the actual published assets.Verified against today's snapshot:
Same problem on the rpm side:
This PR corrects all six affected pages — three unique pages mirrored across the
v4-0-0(current published) andv4-0-1-snapshot(pre-release preview) doc versions:start-here/installing.mdxstart-here/release-channels.mdxcommand-line-tools/installation.mdxSubstitutions are scoped to bleeding-edge contexts only (snippets using
${SNAP_FILENAME_VER}and prosewheels_4.0.0.snapshot.*filename examples). Stable-channel snippets are unchanged — they use${WHEELS_VERSION}and fetch fromwheels-dev/wheels(notwheels-snapshots), and correctly retain the barewheels_/wheels-prefixes because the stable Linux package is still named justwheels.Related Issue
No issue tracking this specifically; surfaced while planning the 4.0.2 release readiness around #2773. Without this fix, users on Linux can't follow the documented bleeding-edge install flow to verify develop-only fixes — including the two other in-flight 4.0.2 PRs:
[wheels.Injector]error)onErrorguardType of Change
Feature Completeness Checklist
Signed-off-by:trailer present.ai/doesn't reference these snapshot filenames)[Unreleased]entry would also conflict with fix(ci): stop double-nesting framework inside Linux .deb/.rpm packages #2776's entry on the same anchor at merge time.wheels_${SNAP_FILENAME_VER}orwheels-${SNAP_FILENAME_VER}.x86_64.rpmpatterns remain anywhere underweb/, (b) fixedwheels-be_/wheels-be-forms present in all six pages, (c) stable-channelwheels_${WHEELS_VERSION}/wheels-${WHEELS_VERSION}.x86_64.rpmsnippets untouched.Test Plan
End-to-end validation (after merge, once next develop snapshot fires):
Scope clarification — why I'm NOT also fixing
apt.wheels.dev/yum.wheels.devinstall instructions — those aren't live yet; current Phase 1 GitHub-Releases-direct-install is the only pathwheels, notwheels-stableor similarwheels-bedocs — already correct; those formulas use independent install commands that don't reference snapshot artifact filenames