Rails Major-Version Upgrade Program Playbook
Upgrade Rails across major versions as a staged program. Audit deprecations, dual-boot against both versions, adopt new defaults deliberately, then cut over with a canary.
Major Rails upgrades change framework defaults, deprecate APIs, and require coordinated gem updates. This program runs the upgrade as a staged, test-guarded migration using a dual-boot setup so the application can run against both the old and new versions until the new one is green.
Phase-by-Phase
Readiness and Deprecation Audit. Run the application with deprecation warnings as errors to surface everything the new version will reject. Build a gem compatibility matrix and a strong test baseline. The audit defines the scope of work concretely instead of by guesswork.
Dual-Boot and Incremental Fixes. Configure the app to boot against both Rails versions selected by an environment variable. Fix deprecations and upgrade incompatible gems on trunk, keeping CI green for the current version while progressively passing under the new one.
Framework Defaults and Config. Adopt the new framework defaults deliberately, one at a time, updating initializers and configuration. Feature flags let risky default changes roll out gradually rather than all at once.
Cutover and Cleanup. Remove the dual-boot scaffolding, deploy with a canary, and watch the four golden signals during stabilization. The program ends when the app runs solely on the new version with no deprecations.
Team and Roles
An architect owns the upgrade strategy and default-adoption order. Backend engineers fix deprecations and gems. QA maintains the test baseline. DevOps manages dual-boot CI and the canary rollout.
Risks and Mitigations
Gem incompatibility is the most common blocker; the compatibility matrix identifies it early and the dual-boot keeps work shippable. Changed framework defaults can alter behavior subtly, so adopt them individually behind flags. Silent regressions are caught by the test baseline. Coordinate so the whole team works against one upgrade branch via trunk-based development.
Success Criteria
Success is zero deprecation warnings, maintained or improved test coverage, steady deployment frequency, and good MTTR through the cutover.
Tooling
Use dual-boot gem configuration, a Git-driven CI matrix testing both versions, feature flags for defaults, and canary deployment. PostgreSQL and Redis remain the data and cache backends.