Skip to content

Commit b54aeba

Browse files
bpamiriclaude
andcommitted
docs(web/guides): fix four review accuracy items against the merged upgrade apply implementation
Re-verified every behavioral claim in upgrade.mdx against the MERGED ##3039 implementation (develop 52be83e, runUpgradeApply() in cli/lucli/Module.cfc + cli/lucli/services/FrameworkUpgrader.cfc): 1. Swap-summary sample now mirrors the real output lines — 'Framework upgraded: old -> new', 'Backup: <path>', and the 'Recover with: rm -rf ... && mv ...' one-liner — instead of the invented label text. Also notes that refusal paths print no backup/restore line (refusals fire before the plan announcement). 2. Both check sample blocks now end with 'Apply with: wheels upgrade apply' (##3039 replaced 'Upgrade with: brew upgrade wheels'); the same-major sample also now shows the real 'Same major version — no known breaking changes.' / 'Scanning for opt-in recommendations...' lines. 3. Prerequisites names 'wheels upgrade apply' as the step that replaces framework code (manual vendor/wheels/ drop-in kept as the by-hand fallback) and clarifies brew upgrade wheels only updates the CLI binary. 4. Documented that a typo'd subcommand (wheels upgrade chekc) prints usage then hard-errors non-zero, per the explicit-verb dispatch. Verified with pnpm verify:docs on all three touched pages (exit 0). The released brew CLI is 4.0.3 (pre-apply), so the apply samples were verified against the merged source as ground truth, not a live run. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Peter Amiri <peter@alurium.com>
1 parent d76ae86 commit b54aeba

1 file changed

Lines changed: 14 additions & 10 deletions

File tree

  • web/sites/guides/src/content/docs/v4-0-0/command-line-tools/wheels-commands

‎web/sites/guides/src/content/docs/v4-0-0/command-line-tools/wheels-commands/upgrade.mdx‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ wheels upgrade check [--to=<version>] [--format=json] [--strict]
2424
wheels upgrade apply [--to=<version>] [--nobackup]
2525
```
2626

27-
Calling `wheels upgrade` with no subcommand prints concise usage listing both verbs and exits 0.
27+
Calling `wheels upgrade` with no subcommand prints concise usage listing both verbs and exits 0. Any other subcommand — a typo like `wheels upgrade chekc` — prints the usage and then hard-errors with a non-zero exit, so a misspelled verb in a script fails loudly instead of looking like a successful run.
2828

2929
### What it does
3030

@@ -43,7 +43,7 @@ Nothing in the project is modified. No files are written. The command does not s
4343

4444
None that the command enforces — but in practice:
4545

46-
- **Commit first.** The scanner is read-only, but the actual upgrade (`brew upgrade wheels`, a fresh `vendor/wheels/` drop-in, etc.) will replace framework code. Have a clean working tree so you can diff and roll back.
46+
- **Commit first.** The scanner is read-only, but the actual upgrade — `wheels upgrade apply` (or a manual `vendor/wheels/` drop-in if you vendor by hand) — replaces framework code. Have a clean working tree so you can diff and roll back. (`brew upgrade wheels` only updates the CLI binary, never your app's vendored framework copy.)
4747
- **Run your tests.** Rerun the test suite after the framework swap, not after this command — `wheels upgrade check` does not exercise anything, it only greps.
4848
- **Internet access** is required when you don't pass `--to=`. The command fetches the latest release tag from GitHub.
4949

@@ -79,18 +79,19 @@ Breaking Changes (2 found):
7979
All Clear (1 checks):
8080
+ Direct WireBox references
8181
82-
Upgrade with: brew upgrade wheels
82+
Apply with: wheels upgrade apply
8383
```
8484

8585
When current and target share a major version, the major-transition note is shown but the advisory scan still runs:
8686

87-
```text title="illustrative — same-major output"
87+
```text title="illustrative — same-major output (trimmed)"
8888
Current version: 4.0.0
8989
Target version: 4.0.1
9090
91-
Same major version — no known breaking changes between majors.
92-
(advisory scan still runs against the same-major patterns)
93-
Upgrade with: brew upgrade wheels
91+
Same major version — no known breaking changes.
92+
Scanning for opt-in recommendations...
93+
94+
Apply with: wheels upgrade apply
9495
```
9596

9697
### What gets checked
@@ -134,13 +135,16 @@ If this is interrupted, restore with:
134135
rm -rf "/path/to/app/vendor/wheels" && mv "/path/to/app/vendor/wheels.bak-20260611-141502" "/path/to/app/vendor/wheels"
135136
```
136137

137-
After the swap, it reports the version transition and backup location:
138+
After the swap, it reports the version transition, the backup location, and the recovery one-liner:
138139

139140
```text title="illustrative — swap summary"
140-
3.5.1 -> 4.0.2
141-
Backed up to: vendor/wheels.bak-20260611-141502
141+
Framework upgraded: 3.5.1 -> 4.0.2
142+
Backup: /path/to/app/vendor/wheels.bak-20260611-141502
143+
Recover with: rm -rf "/path/to/app/vendor/wheels" && mv "/path/to/app/vendor/wheels.bak-20260611-141502" "/path/to/app/vendor/wheels"
142144
```
143145

146+
If a safety check refuses the swap, the command prints only the refusal and exits non-zero — no backup is made and no restore command is shown, because there is nothing to restore.
147+
144148
Safety checks run before any mutation:
145149
- Source (CLI-bundled) and target (`vendor/wheels/`) must each sniff as a valid Wheels framework directory — a generic `box.json` is not sufficient.
146150
- The command refuses to run inside the Wheels repo checkout itself (source = target).

0 commit comments

Comments
 (0)