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.

Pre-Condition

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.

Feedback

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!