How to Upgrade Your Ruby on Rails Application

Ruby on Rails evolves quickly. It may not look like that, but when you go back to your applications, you find them most likely a few versions behind the current stable release. Unfortunately, you cannot simply jump from your current version to the newest one. Instead, you need to upgrade from one major version to the next one (for example: from 4.2.6 to 4.2.11, then to 5.0, 5.1, 5.2). That means the longer you wait, the more work will it take to get to the newest version.

The official Upgrading Ruby on Rails guide explains the required steps in all the details you need to know. However, there are few obstacles I run into that you do not need to repeat.

 

Prerequisites

Before you try anything with upgrading even the simplest Ruby on Rails application, you must ensure that everything your application needs is under version control. It is easy to make a mistake and end up with a situation in which you want to throw all the changes away and start from scratch. Without version control you may not be able to do that. Therefore, check that everything works by starting your application from a fresh checkout.

A high test coverage with automated tests is a must-have. It may look like a good idea to skip that and try to manually test your application after each step in the upgrade process. You may do that once or twice, but then it is too much effort and you stop doing it. The next thing that inevitable happens is that you miss small errors that will lead to big and time-consuming problems down the road. Therefore, spend the time you are willing to do manual tests on your test automation. Only then do you create a value that will stay with your application.

 

The upgrade loop

To ensure your application works at the end, you must follow the upgrade guide and upgrade from one major version to the next. For each version you need to do these steps:

1. Change the Rails version in the Gemfile
2. gem update
3. rails app:update
4. Apply all changes from the upgrade guide
5. Run your tests
6. Fix all failing tests
7. Fix all obsolete messages

Depending on how much you trust your tests you can jump right to the next version without starting your application and manually clicking through the user interface. If you are not so sure, test the main features and if a problem pops up you know that you need to stop and improve your automated tests.

 

Problem 1: Incompatible gem versions

All your gems without a specific version number will be upgraded to the newest one. For some gems this is no problem at all, while others lead to unmet dependencies and stop your application from working.

Should this happen, go to RubyGems.org and look for a version of that gem that was available around the time the version of Rails was released that you currently try to install. Use the x.0 release of the major Rails version, then many years may have passed between this one and the last one you need for the upgrade (Rails 5.0.0 was released in June 2016, while 5.0.7.2 is from March 2019).

If you have found a version number that matches this time range, you can specify it in the Gemfile and run gem update again. You may need to repeat this for multiple gems until everything works together.

 

Problem 2: yanked gems

A rather special case of incompatible versions of gems is a yanked gem. I used the coffee-script-source gem in version 1.1.3 as I wrote the initial application. When I tried to fetch this gem again, I only got this error message from bundler:

Could not find coffee-script-source-1.1.3 in any of the sources

On the version page for this gem on RubyGems.org https://rubygems.org/gems/coffee-script-source/versions/1.1.3 I found the reason for this error:

coffee-script-source 1.1.3
This version has been yanked, and it is not available for download directly or for other gems that may have depended on it.

In my case I could fix the problem with the previous version. The next version had breaking changes and my upgrade would take a lot longer. Your millage may vary, but the next or the previous version should normally work without much changes to your code.

 

Problem 3: Incompatible Ruby versions

Some of your gems may need a more modern version of Ruby itself. Check which version of Ruby is supported by the version of Rails you try to upgrade to and then use the newest one that is supported. This saves you a lot of work and is what you need to do in the end anyway.

Tools like rbenv can help you to install multiple versions of Ruby side-by-side and switch between as you need to.

 

Conclusion

Upgrading a Ruby on Rails application is time consuming. Therefore, prepare for it by making sure you have the necessary hours available to you before you start. If this is not the case, you may better spend the time to improve the test coverage first and postpone the upgrade until you have a high coverage. That will help you later a lot more than a half-upgraded application. And do not forget to read the upgrade guide carefully – that can save you a lot of troubles.