Ruby on Rails Upgrade Guide
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,
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.
Now, update the gem using bundler.
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:
This will ask you for confirmation about
overwriting some of the files.
You might want to keep your existing
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
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.
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.