Article  |  Development

Helpful Resources for Upgrading Your Rails App Version

Reading time: ~ 5 minutes

Helpful Resources for Upgrading Your Rails App Version

Every major version of Rails brings dozens of new features, increased security, and better performance. But depending on your test coverage, developer resources, and time, it's often difficult to prioritize an upgrade. When you're able to update your Rails app, you want it to be as speedy and bug-free as possible.

To help you out, we've rounded up some of the best checklists, tools, tutorials, and articles on upgrading to different versions of Rails. Some are specific to versions 4.x, 5.x, or 6.0, and some will be useful for any upgrade.

Check them out below, and if we missed your favorite article, leave a comment below with the link. We'd be happy to include it.

Upgrading to any Version of Rails

Rails Official Release Guides

The Rails official release guides are, of course, the first place you should begin to research upgrading your Rails app. With each release of the newest version of Rails, a new upgrade guide is also published. Upgrade guides are available from Rails 3.0 to 3.1, all the way up to Rails 5.2 to 6.0. These guides from the official Rails team are helpful for covering the basic changes in each version, and for providing high-level tips on common issues.

Rails Upgrade Checklist

This simple Rails upgrade checklist is one of the most helpful resources for anyone needing to update a Rails app. It’s not incredibly in-depth but provides a rough outline of where to start and what steps to take depending on what version of Rails you’re on. Currently, this checklist is only updated to Rails 4. If you’re interested in submitting pull requests to update the list, you can do that here.


It’s easy to find documentation on what Rails has changed with each release. It’s harder to find specifics on what you need to be changing in your own Rails app. RailsDiff outlines the code changes necessary for each Rails update, from 2.3.6 all the way up to the latest versions of Rails 6. The site gives a visual, line by line demonstration of configuration changes you’ll make in your app.

RailsDiff guide to upgrading Rails

Of course, depending on the Gems you’re using, there will be additional changes you’ll need to make and test in your Rails application. But for someone executing their first upgrade, or if you have no idea where to begin, RailsDiff is an incredibly helpful tool.


Okay, it’s no secret that one of the first things you do when running into an unexpected error is check Stack Overflow. And while you can definitely ask questions about any issues you discover during your Rails upgrade experience, there are also informative answers ready to be found. If you happen to be upgrading from 4.2.6 to Rails 5.0, there’s a full discussion on that.

Reddit /rails

Just like Stack Overflow, Reddit is a common source for answers to web development issues you’re stumped on. Reddit has an entire community dedicated to Rails, where you’re able to ask technical and career-based questions – including issues you come across in your Rails update. Will your answer be delivered with a snarky comment? Maybe. But you’ll get your answer and can get your update completed either way.

Upgrading to Rails 6.x

The official release of Rails 6 will be at RailsConf 2019, but the newest version of Rails is available to use now. And while it may seem risky to immediately upgrade to a new version of the framework, Rails does a great job of vetting their new versions early. The version of Rails that's out pre-release (Rails 6.0.0 release candidate 1) is already being used in production by major companies like Github, Shopify, and Basecamp.

Agile Web Development with Rails 6 (beta)

This book highlights how to build with Rails the way the Rails core team wants you to use the framework. The latest edition covers all of the new features in Rails 6 and Ruby 2.6, so it's perfect for less experienced developers jumping into Rails for the first time and experienced developers alike.

Upgrading to Rails 6 and Getting started with Action Text

Rails developer Pierre-Arnaud Baciocchini breaks down some of the initial steps to upgrading your Rails application to the newest version of Rails: examining test coverage, ensuring you're on Ruby 2.5.0 or higher, and more. He also details what to do to start using the new Action Text feature in Rails 6.0.

We assembled a list of everything we've read so far about the newest version of Rails including new major and unnoticed features included in Rails 6.0. Read our Rails 6 roundup for all of those details.

Upgrading to Rails 5.x

Running on Rails 4.x? It’s easy to let a Rails app get behind while focusing on new features. If you’re planning your upgrade to Rails 5 (here’s some reasons we think you should!) then these links will be helpful.

RailsApps Guide to Updating to 5.0

This article specifically references using RVM to manage Rails versions. You can adapt the principles for chruby or rbenv if that's your preference, or you can follow along exactly for Ruby Version Manager.

Upgrading Shopify to Rails 5

Our friends at Shopify documented their prep work, upgrade strategy, and rollout so we can learn from their mistakes and wins.

Upgrading GitHub from Rails 3.2 to 5.2

Similar to the link above, Github also completed a major Rails version upgrade from 3.2 to 5.2. It's reassuring to see that even a company the size of Github can run into issues prioritizing and completing a big upgrade. Eileen Uchitelle, a Senior Engineer at Github and a member of the Rails core team, shares what she learned throughout the process.

Upgrading to Rails 4.x

There’s no better time than now to start planning your catch-up process. Even if you’re a few versions behind, upgrades are an iterative process and most easily done one version at a time. For apps running on Rails 3.x or below, here are some helpful tips and guides for upgrading to Rails 4.x.

Upgrade to Rails 4 Guide

I came across this guide mentioned in several conversations about Rails 4 upgrades on Stack Overflow. While there are tons of free resources online, at just $10, this eBook may be worth investing in. It’s helpful to have all of your resources in one place when you need to quickly get a Rails update out the door. This guide includes 32 chapters on various Rails 4 features, along with a detailed checklist for upgrading.

RailsCast Upgrading to Rails 4

For visual learners, RailsCast is the perfect place to see your issues resolved in real time. If you're upgrading to Rails 4.x, RailCast has put together a screencast displaying the process for updating. The video takes you through the different spots where key changes will occur, and you can follow along in real time.

Railscast video screencasting

How to Upgrade to Rails 4.2 - Justin Weiss

Justin lays out some (nearly) foolproof tips for upgrading a Rails app to version 4.2. This guide briefly covers testing, Rails gem updates, and more. It doesn’t dig into the nitty-gritty details but is a good high-level view of the best strategy for upgrading.

How to Upgrade a Big Legacy App to Rails 4

If you’re strategizing an upgrade for a large-scale app, this article will give you insight into how one team did it – without having a separate feature branch. This covers the makeup of the development team, how strategy played a part in the update, and the technical changes that were made along the way.

If your development team isn’t able to prioritize an update, this article also helps explain resource allocation and how features and technical debt were balanced. While the update progressed slowly over the course of 20 months, it was completed and the app was improved because of it.

In a perfect world, updates would happen seamlessly with each new release as part of a healthy Rails maintenance plan. But balancing updates with feature releases and budgeting for the work make it easy to delay an upgrade for months or even years.

If you're considering outsourcing your Rails app upgrade so you can focus on your customers, or if you need a guiding hand for updating a large or very outdated app, click below to schedule a call.

We'd love to talk with you about the lessons we've learned from upgrading Rails apps, and find out if our expertise can benefit your business.

This article was originally published in June of 2017. It was updated in April of 2019 to include information about Rails 6.0.

Talk to us about your Rails Upgrade
Browse Articles…

Sign up for our newsletter

Receive a selection of our favorite articles from our blog and around the web straight to your inbox.

Have a project that needs help?

New Call-to-action