Upgrading from 2.x to 3.x

Wheels 3.0 is documented in its own frozen guide. If you are upgrading 2.x to 3.x, use that as your authoritative source — it covers the config directory move, renamed conventions, and every other breaking change in detail.

Wheels 3.0 Guides Frozen documentation for the 2.x to 3.x upgrade.

Config Directory Migration (3.0.0) The specific 2.x to 3.x breaking change most apps hit first.

If you are hopping 2.x to 4.x in one sitting

Do it in two passes, not one:

1. Upgrade 2.x to 3.x first, following the v3.0 guides. Get the app booting on 3.x before touching 4.x.
2. Then read Upgrading from 3.x to 4.x and apply those changes.

Skipping the 3.x landing creates a combinatorial upgrade. Many 2→3 breaking changes assume 3.x semantics once applied, and many 3→4 breaking changes assume the same. Debugging a failure that straddles both hops is painful. Landing on 3.x first gives you a known-good checkpoint.

Why this page is short

The v3.0 guides already document the 2.x to 3.x upgrade in full. Copying that content here would drift out of sync. This page exists only to route you there and to flag the two-pass pattern for anyone jumping straight to 4.x.