docs: add Wheels 3.0 → 4.0 ground-made-up comparison#2125
Merged
Conversation
Companion to the 4.0 feature audit (#2123) and the CHANGELOG catch-up (#2124). Shows, category by category, every capability that changed between the 3.0.0 stable release and 4.0. Rows that didn't change are omitted so the "ground made up" story is readable. Structure: - At-a-glance stats - 12 category tables (ORM, Migrations, Routing, Controllers, Middleware, Views, DI, Jobs/Real-time, Testing, CLI, Packages, Infra/DevOps) — each with 3.0 state, 4.0 state, and delta label - Security posture section — 40+ hardening PRs grouped by area - Peer-framework context — rows where 3.0 trailed Rails/Laravel/Django and 4.0 closed the gap - Reading key Uses strikethrough formatting in the 3.0 column to visually encode "this was missing and is no longer" so readers' eyes land on the 4.0 state. Sourced from CHANGELOG [3.0.0] section + the feature audit. Deltas labeled: New / Formalized / Hardened / Fixed / Breaking / Deprecated / Removed / Renamed / Refactored / Refreshed / Streamlined / Changed. Lives in docs/releases/ alongside the audit for discoverability. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bpamiri
force-pushed
the
peter/wheels-3.0-vs-4.0-comparison
branch
from
3b5a187 to
da0b9a0
Compare
3 tasks
bpamiri
added a commit
that referenced
this pull request
Apr 16, 2026
Repo-wide sweep applying the three-bucket rename rubric to 20 forward- looking documentation files. Companion to #2125 (comparison doc) and #2126 (audit + CHANGELOG follow-up). Rubric applied: 1. Current framework identity → rename to WheelsTest 2. BDD style/pattern name → drop TestBox qualifier, use "BDD syntax" 3. Historical / rename-event / upstream-project references → preserved Files updated (20 total): - docs/wheels-vs-frameworks.md - CLAUDE.md, CONTRIBUTING.md - docs/src/working-with-wheels/{directory-structure,end-to-end-testing, browser-testing}.md - docs/src/command-line-tools/cli-guides/testing.md - tests/README.md - .ai/wheels/testing/{browser-testing,unit-testing}.md - .ai/wheels/{views,controllers,models}/testing.md - examples/{README,starter-app/README,tweet/AGENTS}.md - examples/tweet/.claude/skills/{README,SKILLS-QUICK-START}.md - packages/{legacyadapter/README,sentry/CLAUDE}.md Legitimate retentions (per rubric bucket 3): - "formerly TestBox" history notes in CONTRIBUTING.md - Upstream URL labels pointing to testbox.ortusbooks.com (framed as "Upstream TestBox Docs" for BDD syntax reference) - this.testbox CFML Application.cfc property (back-compat convention) - /tmp/testbox_results.json temp-file names in shell examples CLI command updates where code paths exist: - `box testbox run` → `wheels test run` in tests/README.md and examples/starter-app/README.md (matches Wheels CLI canonical form per CLAUDE.md's testing quick reference) Upstream reference reframing in .ai/wheels/{views,controllers,models}/ testing.md: "Modern TestBox Resources" section retitled to "BDD Reference — Upstream TestBox Docs" with explicit note that WheelsTest inherits the BDD syntax from upstream Ortus TestBox. Deferred to editorial follow-up PRs (complex mix of stale code, CommandBox commands, URLs, and prose requiring verification): - docs/src/working-with-wheels/testing-your-application.md (39 refs) - cli/WHEELS-CLI-ROADMAP.md (15 refs) - examples/tweet/.{claude/commands,opencode/command}/wheels_execute.md Out of scope (historical planning artifacts, per rubric bucket 3): - docs/superpowers/plans/** - docs/superpowers/specs/** Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
4 tasks
bpamiri
added a commit
that referenced
this pull request
Apr 16, 2026
Repo-wide sweep applying the three-bucket rename rubric to 20 forward- looking documentation files. Companion to #2125 (comparison doc) and #2126 (audit + CHANGELOG follow-up). Rubric applied: 1. Current framework identity → rename to WheelsTest 2. BDD style/pattern name → drop TestBox qualifier, use "BDD syntax" 3. Historical / rename-event / upstream-project references → preserved Files updated (20 total): - docs/wheels-vs-frameworks.md - CLAUDE.md, CONTRIBUTING.md - docs/src/working-with-wheels/{directory-structure,end-to-end-testing, browser-testing}.md - docs/src/command-line-tools/cli-guides/testing.md - tests/README.md - .ai/wheels/testing/{browser-testing,unit-testing}.md - .ai/wheels/{views,controllers,models}/testing.md - examples/{README,starter-app/README,tweet/AGENTS}.md - examples/tweet/.claude/skills/{README,SKILLS-QUICK-START}.md - packages/{legacyadapter/README,sentry/CLAUDE}.md Legitimate retentions (per rubric bucket 3): - "formerly TestBox" history notes in CONTRIBUTING.md - Upstream URL labels pointing to testbox.ortusbooks.com (framed as "Upstream TestBox Docs" for BDD syntax reference) - this.testbox CFML Application.cfc property (back-compat convention) - /tmp/testbox_results.json temp-file names in shell examples CLI command updates where code paths exist: - `box testbox run` → `wheels test run` in tests/README.md and examples/starter-app/README.md (matches Wheels CLI canonical form per CLAUDE.md's testing quick reference) Upstream reference reframing in .ai/wheels/{views,controllers,models}/ testing.md: "Modern TestBox Resources" section retitled to "BDD Reference — Upstream TestBox Docs" with explicit note that WheelsTest inherits the BDD syntax from upstream Ortus TestBox. Deferred to editorial follow-up PRs (complex mix of stale code, CommandBox commands, URLs, and prose requiring verification): - docs/src/working-with-wheels/testing-your-application.md (39 refs) - cli/WHEELS-CLI-ROADMAP.md (15 refs) - examples/tweet/.{claude/commands,opencode/command}/wheels_execute.md Out of scope (historical planning artifacts, per rubric bucket 3): - docs/superpowers/plans/** - docs/superpowers/specs/** Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
bpamiri
added a commit
that referenced
this pull request
Apr 16, 2026
Design doc for a new standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md. Scope: - Breaking + migration path (~350 lines) - 10 Breaking items covered with consistent 4-part format: what changed / how to detect / how to fix / opt-out - Legacy Compatibility Adapter documented as soft-landing option - Recommended (not required) migrations section - Single callout link added to existing upgrading.md Spec companion to the feature audit (#2123), 3.0 → 4.0 comparison (#2125), and CHANGELOG catch-up (#2124), which together form the 4.0 release-documentation stack. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bpamiri
added a commit
that referenced
this pull request
Apr 16, 2026
New standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md
covering the 10 Breaking changes in 4.0 plus migration paths:
- Before you start (backup, test environment, CHANGELOG)
- 5-minute upgrade checklist (scannable table)
- Breaking changes — detailed:
* 6 security-hardening default flips (CORS, env-switch, HSTS,
CSRF SameSite, RateLimiter trustProxy, RateLimiter proxy
strategy)
* 1 CLI rename (wheels snippets → wheels code)
* 3 namespace / directory renames (wheels.Test → WheelsTest,
tests/specs/functions/ → functional/, application.wirebox →
application.wheelsdi)
- Legacy Compatibility Adapter (#2015) — soft landing
- Recommended (not required) migrations — 10 items
- Still stuck? — links to audit, comparison, adapter, discussions
Each Breaking item uses a consistent 4-part format:
What changed / How to detect / How to fix / Opt-out
Plus a one-line callout added to the top of the existing
docs/src/introduction/upgrading.md linking to the new guide.
Companion to:
#2123 — 4.0 feature audit
#2124 — CHANGELOG Unreleased expansion
#2125 — 3.0 → 4.0 comparison doc
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
7 tasks
bpamiri
added a commit
that referenced
this pull request
Apr 16, 2026
New standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md
covering the 10 Breaking changes in 4.0 plus migration paths:
- Before you start (backup, test environment, CHANGELOG)
- 5-minute upgrade checklist (scannable table)
- Breaking changes — detailed:
* 6 security-hardening default flips (CORS, env-switch, HSTS,
CSRF SameSite, RateLimiter trustProxy, RateLimiter proxy
strategy)
* 1 CLI rename (wheels snippets → wheels code)
* 3 namespace / directory renames (wheels.Test → WheelsTest,
tests/specs/functions/ → functional/, application.wirebox →
application.wheelsdi)
- Legacy Compatibility Adapter (#2015) — soft landing
- Recommended (not required) migrations — 10 items
- Still stuck? — links to audit, comparison, adapter, discussions
Each Breaking item uses a consistent 4-part format:
What changed / How to detect / How to fix / Opt-out
Plus a one-line callout added to the top of the existing
docs/src/introduction/upgrading.md linking to the new guide.
Companion to:
#2123 — 4.0 feature audit
#2124 — CHANGELOG Unreleased expansion
#2125 — 3.0 → 4.0 comparison doc
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bpamiri
added a commit
that referenced
this pull request
Apr 16, 2026
New standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md
covering the 10 Breaking changes in 4.0 plus migration paths:
- Before you start (backup, test environment, CHANGELOG)
- 5-minute upgrade checklist (scannable table)
- Breaking changes — detailed:
* 6 security-hardening default flips (CORS, env-switch, HSTS,
CSRF SameSite, RateLimiter trustProxy, RateLimiter proxy
strategy)
* 1 CLI rename (wheels snippets → wheels code)
* 3 namespace / directory renames (wheels.Test → WheelsTest,
tests/specs/functions/ → functional/, application.wirebox →
application.wheelsdi)
- Legacy Compatibility Adapter (#2015) — soft landing
- Recommended (not required) migrations — 10 items
- Still stuck? — links to audit, comparison, adapter, discussions
Each Breaking item uses a consistent 4-part format:
What changed / How to detect / How to fix / Opt-out
Plus a one-line callout added to the top of the existing
docs/src/introduction/upgrading.md linking to the new guide.
Companion to:
#2123 — 4.0 feature audit
#2124 — CHANGELOG Unreleased expansion
#2125 — 3.0 → 4.0 comparison doc
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bpamiri
added a commit
that referenced
this pull request
Apr 16, 2026
* docs: spec for Wheels 4.0 upgrade guide Design doc for a new standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md. Scope: - Breaking + migration path (~350 lines) - 10 Breaking items covered with consistent 4-part format: what changed / how to detect / how to fix / opt-out - Legacy Compatibility Adapter documented as soft-landing option - Recommended (not required) migrations section - Single callout link added to existing upgrading.md Spec companion to the feature audit (#2123), 3.0 → 4.0 comparison (#2125), and CHANGELOG catch-up (#2124), which together form the 4.0 release-documentation stack. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: implementation plan for Wheels 4.0 upgrade guide 12-task plan covering: - File scaffold (front-matter + H1) - Before-you-start + 5-minute checklist - 10 Breaking items (3 tasks grouped by theme) - Legacy Compatibility Adapter section - Recommended migrations section - Still-stuck section - Callout link added to upgrading.md - Link integrity audit - Commit + push + PR Each task includes the actual prose/code to write, with verification via grep / wc / link-integrity script. No placeholders; plan is executable end-to-end. Companion to: docs/superpowers/specs/2026-04-16-wheels-4.0-upgrade-guide-design.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: add Wheels 4.0 upgrade guide New standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md covering the 10 Breaking changes in 4.0 plus migration paths: - Before you start (backup, test environment, CHANGELOG) - 5-minute upgrade checklist (scannable table) - Breaking changes — detailed: * 6 security-hardening default flips (CORS, env-switch, HSTS, CSRF SameSite, RateLimiter trustProxy, RateLimiter proxy strategy) * 1 CLI rename (wheels snippets → wheels code) * 3 namespace / directory renames (wheels.Test → WheelsTest, tests/specs/functions/ → functional/, application.wirebox → application.wheelsdi) - Legacy Compatibility Adapter (#2015) — soft landing - Recommended (not required) migrations — 10 items - Still stuck? — links to audit, comparison, adapter, discussions Each Breaking item uses a consistent 4-part format: What changed / How to detect / How to fix / Opt-out Plus a one-line callout added to the top of the existing docs/src/introduction/upgrading.md linking to the new guide. Companion to: #2123 — 4.0 feature audit #2124 — CHANGELOG Unreleased expansion #2125 — 3.0 → 4.0 comparison doc Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <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
1 participant
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
New standalone doc at
docs/releases/wheels-3.0-vs-4.0.mdshowing every capability that changed between Wheels 3.0.0 (2026-01-10) and 4.0. Changes-only format — unchanged capabilities are omitted so the "ground made up" story is the only story.Companion to:
docs/wheels-vs-frameworks.md— 4.0 parity comparison with Rails 8, Laravel 12, Django 5Structure
Why a standalone doc
docs/wheels-vs-frameworks.mdis the 4.0 parity doc — expanding itsRecently Closed Gapssection would overshadow the core parity content.docs/releases/alongside the audit — both are release-cycle docs with a lifetime.Test plan
[3.0.0]section (for 3.0 state)docs/wheels-vs-frameworks.mdfor cross-reference consistencyFollow-ups (separate PRs, from the 4.0 plan)
🤖 Generated with Claude Code