Merged
Conversation
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>
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>
bpamiri
force-pushed
the
peter/upgrade-guide-4.0
branch
from
e8cd1db to
2cd53cb
Compare
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
force-pushed
the
peter/upgrade-guide-4.0
branch
from
2cd53cb to
eab6da1
Compare
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 upgrade guide at
docs/src/introduction/upgrading-to-4.0.mdcovering all 10 Breaking changes in 4.0 plus migration paths. Companion to #2123 (audit), #2124 (CHANGELOG), #2125 (comparison).Spec: docs/superpowers/specs/2026-04-16-wheels-4.0-upgrade-guide-design.md
Plan: docs/superpowers/plans/2026-04-16-wheels-4.0-upgrade-guide.md
Structure (417 lines)
Plus a one-line
{% hint style="info" %}callout at the top of the existingupgrading.mdlinking to the new guide.Breaking items covered
allowEnvironmentSwitchViaUrldefault false in prodtrustProxydefault flippedwheels snippets→wheels codewheels.Test→wheels.WheelsTesttests/specs/functions/→functional/application.wirebox→application.wheelsdiTest plan
Scope notes
This PR deliberately does not:
upgrading.md(separate editorial issue)upgrading.md🤖 Generated with Claude Code