Rails update tips and tricks

In this post, I’m going to give you some advice on how to upgrade a Rails application. Rails 5 has been officially released recently, and I’m pretty sure that many developers are now trying to update their application to the latest version of the framework. Upgrading complex applications requires more time and a good test coverage can be really helpful in order to quickly discover broken features.

Running your test suite should also reveal unsopported gems and code incompatibilities with the upgraded version. Not every gem is ready to work with Rails 5 yet. If a gem does not work, you should check if there’s already a branch with Rails 5 support, or if the latest commit just works. Otherwise, you must resort to another solution or adapt the gem to Rails 5.

After creating a new branch for your app you should follow these simple two steps:

Upgrade using rails:update

⦿ ema:rails_app (rails_upgrade) $ rake rails:update
   identical  config/boot.rb
       exist  config
    conflict  config/routes.rb
Overwrite /Users/ema/dev/project/rails_app/config/routes.rb? (enter "h" for help) [Ynaqdh] a

In this step you should allow rake rails:update to overwrite your files (writing a in the console). Many of your configuration files files will be changed. You’ll need to check each changed file and restore your custom configuration, if you did change something in the past. This operation can be really painful if you don’t know what changes are included in the newer version. If you’re not sure what to discard and what to keep you should look at the Rails upgrade guide.

During this delicate operation I suggest you to use a GUI for git, my favorite one is GitX, to analize each changed file and stage only the relavant lines.

Re-initialize your app

I know it seems strange but if you want to include all the new features you should run rails new your_project in the parent folder of your app:

⦿ ema:rails_app (rails_upgrade) $ cd ..
⦿ ema:project $ rails new rails_app -T -d postgresql
       exist
Overwrite /Users/ema/dev/project/rails_app/README.md? (enter "h" for help) [Ynaqdh] a

Just like with the rails:update command, you should allow to overwrite all the files and then check again each one of them.
After running this command you’ll notice a lot differences compared to the running of the Rails update command.

For example if you upgrade from Rails 4.x to Rails 5 you’ll find the new class ApplicationRecord inside app/models/application_record.rb, you will find Action Cable code inside the files app/assets/javascripts/cable.js and app/channels/application_cable/connection.rb and some other files related to ActiveJob. All these changes are not included if you upgrade using only rails:update.

Gemfile

At this point your Gemfile should be clean, all your gems are gone, only Rails 5 gems are there. Now, with patience, you should add all your gems dependecies and if necessary upgrade them to the latest version.

Other files

Most of the modified files are part of the Rails configuration. Verify all these files and commit only the required changes.

Launch test suite

After incorporating all the changes, you should run your test suite. It’s normal that a major upgrade will break some tests. Fix them and then continue to test the application in the browser, in order to be sure that every part of the application still works as expected.

This workflow seems a bit complicated but remember that you’re working on a different branch so you can take all time you need to test and fix all the problems.