Upgrading some Rails apps is as easy as bundle update rails.
But what if you have one of the other kind of apps? The ones that are still on Rails 4.0, or even 3.2, because you didn’t feel like dragging them kicking and screaming into the future?
Whether you’re facing a quick upgrade or a painful one, these steps will help you get your app to Rails 4.2 as smoothly as possible. And in the process, you’ll learn how to take full advantage of Rails 4.2’s new features.
Read the upgrade guide
You should always start your Rails upgrade by reading the Rails Upgrade Guide.
The upgrade guide will walk you through most of the major changes between Rails versions. It’ll tell you exactly how to change your app to fix the biggest problems you’ll run into. (For example, this change in Rails 4.1 would have caused us hours of pain if we hadn’t known to watch for it.)
But more than that, the upgrade guide will explain why you should make those changes. And that’s important, because it helps you understand which of its suggestions you should follow, and which you can ignore.
And if you want to understand the Rails 4.2 changes more deeply, read the release notes. They’ll introduce you to all the cool new Rails 4.2 features you’ll soon be able to use. If nothing else, it’ll motivate you to get that upgrade done.
Upgrade in steps
When you’re moving to a new Rails version, always upgrade to the newest point version first. And don’t skip minor versions.
So if you want to upgrade from 4.1.6 to 4.2, go 4.1.6 to 4.1.9, and 4.1.9 to 4.2. If you’re starting at 4.0.12, go from 4.0.12 to 4.0.13, then 4.0.13 to 4.1.9, and then from 4.1.9 to 4.2. It might seem like a lot more work, but it’ll save you time in the long run.
Why?
The newest point version of a Rails release has the best deprecation warnings.
Don’t underestimate how useful deprecation warnings can be. If you upgrade in steps, they’ll tell you exactly what will break and how to prevent it. If you jump too far, your app will just plain break, and you’ll have no idea why.
Finally, if a point version Rails upgrade (like from 4.0.9 to 4.0.13) breaks a test, it’ll usually also break during a major or minor upgrade. But those problems are much easier to debug and fix when less has changed.
So here’s what to do:
- Upgrade to the newest point release of whichever Rails version your app is on.
- Upgrade any other gems that keep you from
bundle updateing. - Fix the tests, committing as needed.
- Fix the deprecation warnings, committing as needed.
- Upgrade to the next minor or major version of Rails, and repeat.
Lean on your tests
When you upgrade Rails, your tests will be your first sign that something’s not right. They should be the first thing you run, and the first thing you fix. Don’t even bother trying to get your Rails app to boot before your tests mostly pass.
Upgrade your gems
When a test fails, and it doesn’t look like it’s your fault, it usually means one of your gems needs to be updated.
A Rails upgrade is just about the worst time to upgrade a gem. Since so much of your app is changing, it’s hard to tell if the Rails upgrade broke something, or a gem upgrade broke something, or if you broke something.
But because some gems rely so heavily on Rails internals, this is something you’ll just have to do. So if something inside sass fails, upgrade the sass-rails gem. And hope it doesn’t make things worse.
Take lots of notes
If you’re having a particularly rough Rails upgrade, you’ll have to experiment. You’ll probably do some debugging, tweak some code, or change some tests around.
As you do this, you will forget the changes you’ve made. Some of the things you tried that got you mostly, but not quite, there. Which tests you were going to look at next. Other places you need to change code. Tips to share with coworkers that are upgrading their own apps to Rails 4.2.
So, take lots of notes. Write everything down. Things you tried, and files you changed. Hypotheses you have about why things were failing, and whether they were correct. Which gems you had to update. Behavior that seems weird, and you’ll want to check out more closely later.
You don’t want to make a change, roll it back, realize it was actually the right thing to do, and not remember what you did. So write it down.
A few other resources
In the comments, Miha Rekar pointed to RailsDiff, which shows you the difference between new Rails apps generated under different Rails versions. This is a fantastic way to learn about configuration parameters you don’t need anymore, or new ones you should add to your app.
And Daniel Kehoe wrote a comprehensive guide to updating Ruby and Rails using RVM and RVM gemsets.
The best possible Rails upgrade
Some Rails upgrades are smooth. Things just work. Others are challenging, multi-day or multi-week projects. It depends on your app, your dependencies, and the specific things that Rails changed. But if you follow these steps, you’ll have the best possible upgrade experience.
Are you on Rails 4.2 yet? How did your upgrade go? Did you just have to update a bunch of gems, or are you still chasing down that one last failing test?
(A quick note: I’m going to release Practicing Rails on February 11th! So you only have a few weeks left to get the 25% early access discount.)