How to upgrade Rails 6.1 to Rails 8 without a feature freeze

Why go one version at a time

Each Rails release deprecates behaviour before removing it in a later version. Jumping several versions at once turns a list of clear deprecation warnings into a pile of unexplained failures. Moving one minor version at a time keeps every change small enough to review and roll back.

Step 1: Audit before you touch the Gemfile

• Record the current Ruby and Rails versions and check them against the official Rails maintenance policy.
• List gems that pin Rails or are no longer maintained.
• Measure test coverage of critical user journeys.
• Collect deprecation warnings from logs and the test suite.

Step 2: Set up dual boot

Dual boot lets the same codebase run on two Rails versions. With the next_rails gem, a second lockfile tracks the next version while production keeps using the current one.

# Gemfile
if next?
  gem "rails", "~> 7.0.0"
else
  gem "rails", "~> 6.1.7"
end

$ next_rails --init
$ next bundle install
$ next bundle exec rspec

Add a second CI job that runs the suite with the next version, so every pull request is checked against both.

Step 3: Fix deprecations, then flip framework defaults

Once tests pass on the next version, switch it on in production but keep the old framework defaults. Then enable new defaults one by one from the generated initializer.

# config/application.rb
config.load_defaults 6.1
# enable 7.0 defaults one at a time in
# config/initializers/new_framework_defaults_7_0.rb

Step 4: Release every step to production

Each version step ends in production before the next begins. If something breaks, the change is small and the rollback is a single deploy.

Common blockers

• Classic autoloader. Rails 7.0 requires Zeitwerk; switch on Rails 6.1 first.
• Ruby version. Rails 8 requires Ruby 3.2 or newer; plan the Ruby upgrade alongside.
• Abandoned gems. Replace or vendor them before they block a version step.
• Asset pipeline. New Rails 8 apps default to Propshaft; existing apps can keep Sprockets and migrate later.

Frequently asked questions