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, prioritizing an upgrade is often difficult. You want it to be as speedy and bug-free when you can update your Rails app.
To help you, 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, 6.x, or 7.x; 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
The Rails official release guides are the first place you should begin researching 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 and Rails 6.1 to 7.0. These guides from the official Rails team help cover each version's basic changes and provide high-level tips on common issues.
We get variations of this conversation from our peers. It's common for Rails teams not to run on the latest version. In the linked article, we share our best practices for approaching and scheduling an overdue upgrade.
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 change in your Rails app. RailsDiff outlines the code changes necessary for each Rails update, from 2.3.6 to the latest versions of Rails 7. The site gives a visual, line-by-line demonstration of configuration changes you’ll make in your app.
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 checks Stack Overflow. And while you can 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.
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 can 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 complete your update either way.
Upgrading to Rails 7.x
The official release of Rails 7 was announced in early 2022, 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 its new versions early.
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 7 Ruby on Rails dev Thomas Van Holder has a great guide to starting the process of upgrading to Rails 7. He walks through some of the high-level steps in this article.
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.
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.
Our friends at Shopify documented their prep work, upgrade strategy, and rollout so we can learn from their mistakes and wins.
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.
I encountered 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 get a Rails quick update out the door. This guide includes 32 chapters on various Rails 4 features and a detailed checklist for upgrading.
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.
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.
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 can’t 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.
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 March of 2023 to include information about Rails 7.x.