Posted about 3 years ago. Visible to the public.

How to upgrade Rails: Workflow advice

When upgrading Rails versions -- especially major versions -- you will run into a lot of unique issues, depending on the exact version, and depending on your app.

However, it is still possible to give some generic advice on how you want to tackle the update in principle.

If you are not really confident about upgrading Rails, have a look at Rails LTS Archive .

How many update steps?

Besides the Rails upgrade itself, you might also want to upgrade your other gems and upgrade your Ruby version.
First decide in how many steps you want to run the upgrade. I suggest to:

  • Do a separate step for each major Rails version (A). So, if you want to upgrade from Rails 3 to 5, I would do it in two steps 3.x -> 4.2 -> 5.2.
    • Upgrade your gems together with Rails if possible.
  • Upgrade Ruby in a separate step.

If your code base is very large you might need to go in smaller increments. The Rails guides suggest to not skip minor versions, but I have not found that to be necessary, and it will cause some duplicated work.

Upgrading gems at the same time might also be contentious, because it introduces additional complexity. On the other hand, it might also solve compatibility issues in those gems. I prefer to simply upgrade all gems together with Rails.

Workflow for each major Rails upgrade (A)

  • Upgrade Rails and gems

    • Update your Gemfile. Temporarily, set an exact Rails version, (e.g. gem 'rails', '= 5.2.1').
    • Run bundle update.
    • Relax the Rails version in your Gemfile again (e.g. gem 'rails', '~> 5.2.1').
    • Run bundle install.
  • Clean out your tmp folder

    • It contains cache files in the format of earlier versions
  • Update your Rails config

    • Run rails app:update. This will try to write all configuration like it would for a new Rails app, and show you the diff to your current code.
  • Check the official Rails upgrade guide

  • Get rails console running

    • Fix all errors until the Rails console does not crash while starting up.
    • Ignore deprecation warnings for now.
  • Get rails console running with eager loading

    • Enable config.eager_load = true in development.rb.
    • Fix all errors until the Rails console does not crash while starting up.
    • Disable eager loading again.
  • Get rails server running

    • Fix all errors until rails server can render a page.
    • Click around a bit. Fix all errors you can find.
  • Fix tests

    • Fix unit tests.
    • Fix integration tests.
  • Upgrade to new framework defaults Archive

    • Flip each config in config/initializers/new_framework_defaults_x_x.rb one by one
    • For configs that should be kept, move the old default to the application.rb file with and add a comment for the reason
    • Remove config/initializers/new_framework_defaults_x_x.rb and change the config.load_defaults to the new Rails version.
  • Fix deprecation warnings.

    • Run your tests and fix all deprecation warnings.
  • Check if you want to update all your gems afterwards

Also see Upgrading Ruby from 1.8.7 to 2.3.5.

Flaky tests are tests that sometimes fail for no obvious reason. They are the plague of many end-to-end (E2E) test suites that automate the browser through tools like Capybara and Selenium.

Join our free training event and learn to fix any flaky test suite, even in large legacy applications.

Owner of this card:

Tobias Kraze
Last edit:
4 months ago
by Emanuel De
About this deck:
We are makandra and do test-driven, agile Ruby on Rails software development.
License for source code
Posted by Tobias Kraze to makandra dev
This website uses short-lived cookies to improve usability.
Accept or learn more