Repository navigation
docs: tutorial accuracy sweep — chapters 1-6 - #2395
Merged
Merged
Conversation
Bundles 9 fixes uncovered by the 2026-04-30 fresh-VM tutorial bake. Each chapter is a focused edit; the bundle ships one PR / one CI run since they all live under web/sites/guides/. Chapter 1 (Hello, Wheels): - Drop `Controller.cfc` and `Model.cfc` from the "What got created" file tree — `wheels new` doesn't emit those base classes; the tree was aspirational. Add `rewrite.config` at the repo root, which IS emitted but wasn't listed. Finding #15. - Add a "First start downloads ~74 MB" Aside before the welcome-page step so a 30-second wait isn't a surprise. Finding #16. Chapter 2 (Your First Model): - Replace the made-up `Migration complete.` Expected output with the shape the runner actually emits today (`Migrating from 0 up to <ts>` + `Created table posts`), and note that the wording can drift across snapshots so readers verify on the `Created table` line. Finding #10. - Update the `t.timestamps()` description to mention all three columns it adds (`createdAt`, `updatedAt`, `deletedAt`) and link forward to Part 5's soft-delete callout. Previously claimed only two columns. Chapter 3 (CRUD Scaffold): - Rephrase the scaffold caution: it does NOT unconditionally append `.resources("posts")` to routes; it only appends when no resources line for the model exists. Chapter 2 already adds one, so the file is left alone. Finding #13. - Update the "generator emits findByKey(params.key) everywhere" claim — actually it uses `params.post` (route model binding) on key-scoped actions; only positional helpers fall back to `findByKey`. Finding #14. Chapter 4 (Validations + Turbo Frames): - Drop the manual `<label>` wrappers around helpers in `_form.cfm` and use the helpers' own `label="..."` argument instead. The previous shape produced nested `<label>` elements — exactly what chapter 3's caution about object-bound helpers warned against. Finding #11. Chapter 6 (Authentication, Part 6b): - Name `app/events/onapplicationstart.cfm` explicitly as the place to register the session strategy, and explain why `config/app.cfm` is the wrong place (`Application.cfc` this-scope, DI container not yet initialized). The previous "or equivalent on-init block" hedge cost the runner real time. Finding #6. - Recommend scraping `<meta name="csrf-token">` uniformly for curl smoke tests instead of mixing meta-tag-vs-form-input rules. Some forms (login raw inputs, comments, basecoat-rewritten views) don't always include the hidden input. Finding #7. - Replace the `--data-urlencode` recipe with a known-working raw `--data` form that pre-encodes brackets and `@`. The previous "use the `=` separator" advice was incomplete — Lucee's form parser treats any bracketed key as a nested-struct path regardless of encoding form. Finding #8. Findings deliberately not addressed in this PR: - #9 (soft-delete callout) — verified against current code: `t.timestamps()` emits all three columns including `deletedAt`, and `softDeleteProperty` defaults to `deletedAt`. Chapter 5's callout matches reality. The runner's snapshot-1660 observation likely predates the current behavior. - #12 (cosmetic migration drift) — aligning the docs to the generator's uglier emitted shape is value-negative; either source can drift again in a future release. - #17 (silent `brew tap`) — `exit 0` with no output is brew convention; adding a "no output expected" note is noise. - #19 (chapter 6 Compare table renders as wall) — markdown source is well-formed GFM; if the rendered output is broken it's a build/CSS issue not a source issue. Investigate in a follow-up if reproducible. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 of 3 tasks
bpamiri
added a commit
that referenced
this pull request
May 1, 2026
…eadless brew install (#2398) Three follow-ups from the 2026-05-01 fresh-VM tutorial run that survived the recent doc sweeps (#2395, #2396). F8 — chapter 6's "known-working signup smoke test" regex assumed `name="csrf-token" content="..."` attribute order, but Wheels' `vendor/wheels/view/miscellaneous.cfc:404` `$tag` helper sorts attributes alphabetically for deterministic test output, so the actual emit is `content="..." name="csrf-token"`. The old regex returned an empty TOKEN and POST silently failed with `Wheels.InvalidAuthenticityToken`. New regex matches the actual order, plus an explanatory note so future readers know to check attribute order if the scrape ever returns empty. F7 — chapter 2 said "feel free to keep the generator's timestamp instead" of renaming to `20260419120000`. That sounds permissive but is actually a footgun: chapters 5/6 hardcode timestamps `20260419130000`, `20260419140000`, `20260419150000` for comments / users / add_user_to_posts. If the posts migration sorts after them (e.g. May 2026 from a current-day generator), the dev DB still works because migrations apply incrementally as files are added — but the test DB in chapter 7 runs them all from scratch in timestamp order, hits `add_user_to_posts` before `posts` exists, and bails. Now the rename is mandatory with a callout explaining the dependency chain. F1 — the install page only documented the interactive Homebrew installer. That installer's `sudo -n true` precheck always fails in a non-interactive context (CI, agents, packer, provisioning scripts), even with `NONINTERACTIVE=1` set. Added a "Headless / non-interactive installs" caveat with three concrete options (user-prefix `git clone`, pre-baked image, Ansible's homebrew module) and a recommendation for the common agent/CI VM case. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
bpamiri
added a commit
that referenced
this pull request
May 2, 2026
…F11, F13, F18) (#2411) Bundles seven small fixes from the 2026-05-01 fresh-VM tutorial run that weren't urgent enough to ship as separate PRs. Each chapter is a focused edit; the bundle ships one PR / one CI run. start-here/installing (F4 partial): - Hoist `brew install openjdk@21` from inline prose into a code block inside the Java prereq Aside. The Aside placement is fine (Java is a prerequisite, not a Wheels-specific step), but a copy-paste-friendly code block makes it scannable for users skimming for commands. Did NOT promote Java to step 1 of the macOS tab — that would push the Wheels-specific steps to 2/3/4 for marginal benefit. 02-first-model (F6, F11 setup): - Tweak the "intentionally slim" lead-in so users learn upfront that the generator ships with `validatesPresenceOf` rules they'll drop here and revisit in Part 4. The earlier wording suggested the generator omits validations entirely, which then read as a contradiction when the next paragraph says to remove them. - Add a tip introducing `wheels generate migration` (and the `g` alias) right where users see the first auto-generated migration. Chapter 5 mentions the shortcut parenthetically; this gives readers a forward-link to it instead of seeing it for the first time inline. 03-crud-scaffold (F7): - Fix the inaccurate "same shape as this tutorial's" claim about the scaffold's emitted controller. The scaffold uses a `findRecord` filter + `variables.record` reference; this tutorial uses route model binding's `params.post`. Both are valid; the chapter now says so explicitly instead of pretending they're identical. 05-comments-streams (F10, F11 follow-through): - Restore `allowBlank=true` on the `validatesLengthOf(property="title")` line. Chapter 4 explained at length why `allowBlank=true` is needed to avoid double-firing alongside `validatesPresenceOf`; chapter 5 silently dropped it from the same Post.cfc snippet, regressing chapter 4's behavior on a verbatim paste. - Update the `wheels g migration` parenthetical to reference its introduction in chapter 2 instead of presenting it as new. 06-authentication (F13): - Add a working `buttonTo` snippet for logout in the "Test 6a manually" section. The chapter referenced `/logout` abstractly but never showed a known-good way to hit it from a view (DELETE routes need a form, not a link). Now there's a one-line `buttonTo` that uses the named route + method=delete, with a short note that the same shape is what chapter 3's Delete buttons use. cli/lucli/Module.cfc + 07-testing-deploying (F18): - `wheels browser setup` now ends with both invocation forms named explicitly: `wheels test --filter=browser` (canonical, matches the docs) and `wheels browser test` (alias). Previously the CLI suggested only the alias, while the docs used only the canonical form, so users saw two different commands without knowing they were equivalent. Chapter 7 already uses the canonical form; no chapter edit needed. Findings deliberately NOT addressed: - F8 (params.post works without binding=true): Verified against Dispatch.cfc:469-475 — binding is OFF by default at both per-resource and global level. The chapter's claim is correct; the user's report observation likely came from an environment where the Posts.cfc had already been replaced with the chapter's snippet, OR an environmental quirk unrelated to scaffold output. - F5 (generated migration cosmetic differences): Same triage as PR #2395's deliberate skip of the same finding under its prior number — aligning docs to the generator's emitted shape (`force='false'` triplet) is value-negative since either source can drift again. F4 partial, F6, F7, F10, F11, F13, F18 from the 2026-05-01 fresh-VM tutorial run. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bundles 9 fixes from the 2026-04-30 fresh-VM tutorial bake into a single doc-sweep PR (one CI run, one review pass). Each chapter is a focused edit; nothing touches code or tests.
Findings addressed
app/events/onapplicationstart.cfmexplicitly as the strategy-registration site; explain whyconfig/app.cfmis wrong<meta name=\"csrf-token\">scrape uniformly across all forms--data-urlencoderecipe with a known-working raw--dataform<label>wrappers; use helpers'label=\"...\"arg (no more nested<label>elements)findByKey(params.key)claim — generator usesparams.postlike the tutorialController.cfc/Model.cfcfrom file tree; add realrewrite.configFindings deliberately NOT in this PR
t.timestamps()addsdeletedAt(vendor/wheels/migrator/TableDefinition.cfc:372-376) andsoftDeleteProperty=\"deletedAt\"(vendor/wheels/events/init/orm.cfm:27). Chapter 5's callout matches current code; runner's snapshot-1660 observation predates the behavior.force='false', id='true'triplet) is value-negative — either source can drift again.brew tapexits 0; adding a "no output expected" note is noise.Companion PRs
Test plan
🤖 Generated with Claude Code