If you’re reading this, you’re probably contemplating a long painful process of getting your Rails app to a newer version. I recently updated a Rails app from 3.2 to 4.2, and this guide contains the general guidelines to follow for making the upgrade easier.

If your Rails app is on version 4.0.x or below 3.2, it’s very important that you upgrade immediately, since they no longer receives security updates.

Make sure your tests pass

Having a good test suite makes Rails upgrades so much easier. This will help you catch many subtle bugs that might appear as a result of the upgrade. Make sure you have a decent suite of tests and they are all passing before you start with the upgrade.

Make incremental upgrades

If you’re on Rails 3.2, it is tempting to upgrade directly to Rails 4.2. Avoid this. Instead, upgrade first to 4.0.x, then 4.1.x, and finally 4.2.x.

Making incremental upgrades allows you to focus on what has changed in each of those versions. If you run into problems, it is easier to figure out what changed between the minor versions rather than looking at all the changes.

I followed this guideline in a project where I was upgrading from 3.2 to 4.2, and the final step from 4.1 to 4.2 was so easy that I was ready to deploy in less than 15 minutes.

Upgrade other dependencies first

Before upgrading rails, it’s a good idea to upgrade other dependencies to make sure you have compatible versions of those gems. To check for newer versions of gems in your bundle, use the bundle outdated command.

This will list all the dependencies that have a newer version than the one in your Gemfile.lock. Go through the list and look for gems that might not be compatible with the newer Rails.

Check what has changed

The official Rails Upgrade Guide has details about the major changes that might cause problems during the upgrade. It’s very important that you take a close look at the relevant section of this guide.

Apart from that, Railsdiff.org lets you see the diffs between the files generated by various versions of Rails. That’s another way to understand what has changed between the versions.

Upgrade the Rails gem

Update the Gemfile with the newer version of Rails.

- gem 'rails', '4.0.13'
+ gem 'rails', '4.1.10'

Now, update the gem using bundler.

bundle update rails

Run the rake task

Rails provides a very helpful rake task to help with updating your config files. Before doing this, remember that this will replace many of the files in your config directory. Run the rake task:

rake rails:update

This will ask you for confirmation about overwriting some of the files. You might want to keep your existing config/routes.rb file.

Review the diffs

Before you commit the changes, take a close look at the diffs and find out what has changed. You might have made changes to your config files that might got overwritten by rake rails:update. so you might need to compare the diffs to make sure things like your mail configuration for production hasn’t been changed to the Rails defaults.

Fix the tests

At this point, you’ll most probably run into a some failing tests. Make sure you’re back to green before continuing. Also pay attention to the deprecation warnings that you might come across when running the tests. Your app might run fine despite these warnings, but fixing them now would save you a lot of time during the next upgrade.

Wrapping up

This guide covered the general guidelines to be followed for an upgrade to any version of Rails. If you’re looking for guides that cover upgrades to a specific version of Rails, you might want to refer to some of the articles listed below.

• Rails Guides: A Guide for Upgrading Ruby on Rails
• How to Upgrade to Rails 4.2 - Justin Weiss
• RailsApps: updating to Rails 4.2
• Case Study: Upgrade to Rails 4.1
• Migrating existing session cookies while upgrading to Rails 4.1 and above