Upgrading
Upgrading Wheels
Upgrade an existing app to a new version of Wheels. Start with the policy, then follow the version-specific guide for the jump you’re making.
Versioning policy
Section titled “Versioning policy”Wheels follows Semantic Versioning 2.0.0. The CHANGELOG.md at the repo root declares this explicitly and follows the Keep a Changelog format — release sections include the standard Added, Changed, Deprecated, Removed, Fixed, and Security headings alongside more granular ones (Bug Fixes, Breaking Changes, per-layer enhancement groups, and others), so don’t expect every release to use exactly those six.
- Major (
3.x→4.x) — breaking changes are allowed. Read the upgrade guide for that jump before you touch code. - Minor (
4.0→4.1) — additive only. New features, no breaking changes to supported APIs. - Patch (
4.0.0→4.0.1) — bug fixes and security patches. Safe to apply without reading release notes, though you still should.
Deprecations land in a minor release with a log warning and stay functional until the next major. Check the Deprecated section of every release you pass through.
Where to find the current version
Section titled “Where to find the current version”Two sources, in order of authority:
- Runtime —
application.$wheels.versionis the runtime truth. It is populated at application start fromBuildInfo, which readsvendor/wheels/wheels.json. Don’t go looking for a readable literal invendor/wheels/events/onapplicationstart.cfc— there isn’t one. In the source repo the manifest carries the placeholder@build.version@; the build pipeline substitutes the real semver (e.g.4.0.3) in distributed apps. CHANGELOG.md— the most recent non-[Unreleased]heading.
If the two disagree, the runtime value wins — that’s the version your app actually boots against.
Release cadence
Section titled “Release cadence”Wheels doesn’t ship on a fixed schedule. Releases go out when the changelog entries warrant one and the test matrix is green. The git tag history is the authoritative record — git tag --sort=-v:refname shows the latest release (currently v4.0.3, released 2026-06-09; the 4.0 line went GA 2026-05-12 with v4.0.0). Pre-GA builds were tagged in a v4.0.0-SNAPSHOT+N series — the +N suffix is a continuous build number, not a release.
Don’t assume a release date. Watch the releases page on GitHub and subscribe to the repo if you need to know when a tagged build lands.
Upgrade philosophy
Section titled “Upgrade philosophy”Four rules, in order:
- Read the version-specific guide first. The pages below enumerate every breaking change and the migration path for each one. Skimming is a false economy.
- One major at a time. Going from 2.x to 4.x means doing the 2.x→3.x upgrade, verifying your app boots and tests pass, then doing 3.x→4.x. The guides assume you’re coming from the previous major, not two back.
- Upgrade the framework separately from the engine. Wheels runs on Lucee 5/6/7, Adobe ColdFusion 2018/2021/2023/2025, and BoxLang. Change one variable at a time — framework version, then engine version, not both together. When something breaks you’ll know which change caused it.
- Run your full test suite against the new version before deploying. If you don’t have one, the upgrade is also the moment to start — even a handful of smoke tests will catch 90% of regressions.