docs(web/guides): performance notes for 2.x upgraders (#3213)

[bpamiri]

What & why

Issue #3213's literal ask — a readable 2.x-vs-4.x performance writeup — never shipped anywhere in
the guides or the blog; the measured numbers lived only in PR/issue comments. This adds
web/sites/guides/src/content/docs/v4-0-0/upgrading/performance-notes.mdx ("Performance Notes
for 2.x Upgraders") and registers it in the v4-0-0 sidebar under Upgrading & Releases (avoiding
the known orphan-page trap).

Content (measured numbers only — no invented benchmarks)

• The reported regression: same RocketUnit suite, 274 s on 2.5 vs 1,599 s on 4.0.3 (reporter's
  environment: Lucee 5 on Tomcat) — quoted from the Wheels 2.x > 4.x Performance Comparison #3213 body.
• Root cause + fix from perf(model): cache mixin-integration plan to fix per-instance overhead (#3213) #3236 (merged 8f73b77): per-instance mixin re-integration; measured on
  Lucee 7 + SQLite: 2,000 × model().new() 2,772 ms -> 1,513 ms (~1.8x), framework suite
  33.3 s -> ~22 s. Notes the abandoned ~5.8x prototype-clone follow-up as a dead end, per the
  issue thread.
• June 2026 profiling baseline: cold first request ~1.2-1.3 s with ~85% Lucee compiler time,
  warm serving ~0.38 ms in-JVM, dev debug bar ~34% throughput cost (stated as the measured
  dev-only overhead — the profiling record shows the bar costs ~34%, so the page frames it as a
  benchmarking caveat rather than a shipped reduction).
• How upgraders get the fix: bleeding-edge channel (fix missed the v4.0.5 tag by one day) until
  v4.0.6 ships, with wheels upgrade check/apply steps and a link to the Release Channels guide.

Test evidence

• Guides site builds clean: pnpm run build in web/sites/guides — 445 pages,
  /v4-0-0/upgrading/performance-notes/index.html emitted; sidebar JSON validates.
• Full core suite (Lucee 7 + SQLite, isolated worktree server): 4758 pass / 0 fail / 0 error
  (docs-only change; suite unaffected by construction).

Scope

Docs only — no framework, CLI, or app code. No blog post (publishing admin is out of scope here).
Closure of #3213 waits on the v4.0.6 cut, which ships the #3236 fix to stable.

Refs #3213

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — This PR adds a "Performance Notes for 2.x Upgraders" guide page (performance-notes.mdx) and registers it in the v4-0-0 sidebar under Upgrading & Releases, closing the documentation gap from #3213. The page is careful, well-sourced, and sticks to measured numbers. I verified every substantive claim (the #3236 attribution, the linked pages, the frontmatter/import conventions) and they hold up. One user-facing command in a copy-paste code block is wrong/inconsistent with the rest of the guides — a non-blocking docs nit. Verdict: comment.

Docs

performance-notes.mdx:68 — wheels server start should be wheels start. The "How to get the fix" code block ends with a wheels server start line.

The branded CLI exposes the dev-server lifecycle command as wheels start (cli/lucli/Module.cfc:1002 — public string function start(); the MCP-hidden list at Module.cfc:186 registers "start", not server). server start is LuCLI's internal subcommand, not the user-facing verb. Every sibling guide page uses wheels start:

• basics/routing.mdx:162, basics/migrations.mdx:29, basics/seeding.mdx:88 — all point users at wheels start
• basics/database-and-multiple-datasources.mdx:57 — wheels stop then wheels start

and CLAUDE.md documents the command as wheels start / wheels stop. A reader copy-pasting this block gets an inconsistent (and likely invalid) command. Change line 68 to wheels start.

What I verified (no findings)

• #3236 attribution is accurate. git log confirms 8f73b77b5 perf(model): cache mixin-integration plan to fix per-instance overhead (#3236) — the commit the page cites for the fix.
• Both linked pages exist. /v4-0-0/start-here/release-channels/ maps to start-here/release-channels.mdx; the sidebar link /v4-0-0/upgrading/performance-notes/ matches the new file's route.
• wheels upgrade check / wheels upgrade apply are real, documented commands (command-line-tools/wheels-commands/upgrade.mdx, upgrading/3x-to-4x.mdx:404-405).
• Frontmatter and import conventions match prior art. type: explanation is used by 5 other v4-0-0 pages; the import { Aside } from '@astrojs/starlight/components'; line is the exact string used by 18 existing pages.

Commits

Clean. Single commit docs(web/guides): performance notes for 2.x upgraders — valid type (docs), scope allowed (unrestricted), header ~52 chars, sentence-case. PR title matches and is a valid conventional-commit header. No changelog fragment is expected for a docs-only change.

Nice work keeping the page to measured numbers only and citing the profiling caveats (debug-bar overhead as a benchmarking gotcha, not a claimed reduction). Fix the one command and this is ready.