Ruby on Rails Upgrade Pre-Flight Checklist

When to Use This Checklist

Use this checklist before upgrading a Ruby on Rails application across a major version, such as Rails 6 to 7. Rails upgrades bring framework default changes, autoloading shifts, and gem compatibility breaks. The framework's app:update task and the official upgrade guide do much of the heavy lifting, but only if you prepare the codebase first.

How to Use This Checklist

Establish a green baseline test run, then resolve all deprecation warnings on the current version; Rails surfaces upcoming breaking changes as deprecations. Audit gems for target-compatible versions before you start. Run app:update and adopt new framework defaults incrementally through the generated initializer rather than all at once. Validate database migrations on a production-like copy and re-run the full suite on the target version.

Roll out behind a canary and keep the previous release deployable.

What Good Looks Like

A clean upgrade has zero deprecation warnings before the jump, every gem on a compatible version, and new framework defaults adopted deliberately. The test suite is green on the target version, migrations run cleanly, and a bundle scan shows no vulnerable gems. The release ships behind a canary with the prior version ready to roll back.

Common Pitfalls

Upgrading with unresolved deprecation warnings hides exactly the changes that will break. Flipping all new framework defaults at once makes failures hard to isolate. Teams forget that autoloading and asset pipeline changes can break in subtle, runtime-only ways. Skipping a canary turns a gem incompatibility into a production incident.

Related Resources

See the test pyramid and code coverage best practices for your safety net, continuous integration best practices for the pipeline, and canary release practices for rollout.