Posted 9 months 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.

How many update steps?

Besides the Rails upgrade itself, you might also want to

  • upgrade your other gems
  • upgrade your Ruby versions

First decide in how many steps you want to run the upgrade. I suggest

  • To do a separate step for each major rails versions. 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 Ruby in a separate step.
  • Upgrade your gems together with Rails if possible.

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.


  • 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.
  • 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.
  • Fix deprecation warnings.
    • Run your tests and fix all deprecation warnings.

Also see Upgrading Ruby from 1.8.7 to 2.3.5.

Growing Rails Applications in Practice
Check out our new e-book:
Learn to structure large Ruby on Rails codebases with the tools you already know and love.

Owner of this card:

Tobias Kraze
Last edit:
8 months ago
by Dominik Schöler
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 cookies to improve usability and analyze traffic.
Accept or learn more