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.

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.
  • In many cases updating to the highest subversion of the specific rails version is the best choice (e.g. when updating to rails 5 you would update to 5.2.8.12), since the most errors for this rails version have been solved.
• Upgrade Ruby in a separate step. Note that newer versions of Rails may require newer versions of Ruby.
  • Try to choose the highest compatible ruby version as well.

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)

• Take note of patches and quirks for your specific version upgrade: Upgrade Rails: Awareness list . You may want to implement them in a later step but it's helpful to know issues beforehand.

• Upgrade Rails and gems

  • If you upgrade from a Rails LTS to newer version, check Updating Rails LTS to a newer version or Installing Rails LTS after the upgrade again
  • Update your Gemfile. Temporarily, set an exact Rails version, (e.g. gem 'rails', '= 5.2.1').
    • If you're upgrading Rails LTS, requiring Rails requires multiple lines that differ between major versions. Use the latest Gemfile snippet from the Rails LTS docs.
  • Run bundle update
    • This will upgrade all your gems, ignoring versions locked in Gemfile.lock.
    • This might lead to conflicting gem versions due to conflicting dependencies. You might have to update (bundle update [gem names]) the necessary gems first or find a compatible gem version(s) setup by adding constraints to your Gemfile.
    • Note that upgrading all your gems will probably cause errors due to API changes further down this process.
      • In that case check if you can migrate your code to the new gem API easily.
      • If the migration becomes non-trivial, check if you can find an older gem version that has better compatibility with your existing code.

• 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.
  • If you need an overview of all possibly applied changes throughout the update you can check the changes applied to an empty rails app Show archive.org snapshot .

• Check the official Rails upgrade guide

  • Rails has official upgrade notes Show archive.org snapshot . Read through the relevant sections and make the appropriate changes.

• 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 Show archive.org snapshot

  • 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.

• If you have added many constraints in your Gemfile to find compatible versions, remove or relax those constraints to enable future upgrades.

  • Run bundle install so your Gemfile.lock updates as well.

• Keep one commit for every successful rails version update step.

• Take care of patches that should be applied: Upgrade Rails: Awareness list