This 7-step guide is formulated based on our recent experience of performing multiple Rails upgrades on a client project, including a major version upgrade (4.x -> 5.0) and minor upgrade (5.0 -> 5.1).

  • Applicable to small/medium-size codebase, where your team is able to perform upgrade in a non-main branch.
  • If you have a large team where branching off is not feasible, read the experience report from Shopify and Nulogy team.


During the upgrade, you need an automated mechanism to surface breaking changes and verify that they have been fixed. In our case, we have:

  1. Automated test suite - good coverage to trigger breaking changes.
  2. CI build - setup to run when commits pushed to non-main branch.

7-Step Guidelines

To make this easy to digest, the steps are written in short bullet points. Let me know if you want me to elaborate on some of these steps:

  1. Create a blank Rails app (new version), use it as reference app later.
  2. Create new branch.
    • Push commits after every step - so that CI builds reveal breaking changes.
    • Merge/rebase main branch from time to time.
  3. Upgrade gems.
    • Add new gems - copy over from reference app’s Gemfile.
    • Upgrade rails gem - it usually fails when there are outdated gems.
    • Handle outdated gems:
      • Upgrade gem - use the version that supports new Rails version.
      • Remove gem - if no longer needed in new Rails version.
  4. Run rails app:update to update config/bin files.
    Recommended way:
    1. Open reference app side-by-side in text editor.
    2. When rails app:update prompts to change a file, edit manually in text editor by comparing the same file in reference app.
  5. Fix all breaking changes/errors.
    • Silence deprecation warnings first, prevent it from flooding CI build output:
      # config/application.rb
      require "rails/all"  # right after this line
      # To silence deprecation warnings
      ActiveSupport::Deprecation.silenced = true
    • Create new branch to fix one error at a time.
  6. Fix all deprecation warnings.
    • Turn on deprecation warnings.
    • Create new branch to fix each deprecation warning.
  7. Merge back into main branch.


Are you using a different approach to upgrade your Rails apps? Is there something you wish to see in this guide? Share your thoughts and feedback with us!