Upgrading your Rails application is a task that sounds deceivingly simple. Upgrades often come with unforeseen complexities and bumps in the road. This leads to these types of projects often being shifted to the bottom of the priority list to be continually postponed.
You can do your best to prepare: read the Rails upgrade guides, peruse StackOverflow, knock on wood, etc. But the truth is that every Rails app upgrade is different. Different gems lead to unique complexities, every company’s priorities and timelines vary, and internal processes can complicate things.
If you’re operating as a lonely island on a Rails upgrade, it can also be helpful to lean on the experience of others. Don’t ever think that big companies don’t struggle with modernizing apps if you’re on a small team. We have been approached by teams of 25+ developers who have had more issues prioritizing and completing a Rails upgrade than teams of one or two developers.
We’ve gathered some tales from around the web of Rails version upgrades at various companies. How did they structure their plan? How was this work prioritized with other features? What types of people worked on the upgrade – and how many?
Babbel
Babbel is the world’s best-selling language learning app. It’s supported by Ruby on Rails (among other frameworks). They wrote back in 2015 about modernizing their Ruby on Rails monolith app from Rails 3 to Rails 4 with zero downtime for their users.
This upgrade tale is focused on the organization of the work and the team responsible for the work. You’ll see this mirrored in other upgrade stories as well. Understanding the technical aspects of an upgrade is helpful, but only if you’re set up for success to actually get the work done.
Key takeaway: If you’re part of an engineering team, organize a task force to get the upgrade done. We’ve heard many stories from companies with a full team of engineers who are unable to prioritize an upgrade mixed in with regular feature work. By assigning a team and making the modernization process their priority, it’s more likely to get done.
Nulogy
Nulogy is a SaaS company that connects CPG brands and their strategic suppliers. Their application was a large codebase, consisting of ~530k lines of code and 216 gems. The beginning of their upgrade saga shares a similar story that others have experienced – the upgrade was such a daunting task that, without organization, it just wasn’t going to get done.
They formed a Rails upgrade team comprised of representatives from the individual engineering teams within their department. This upgrade-focused team split up the work into small enough pieces that the individual engineering teams could complete that work during an iteration.
In this article, Nulogy also shares its tips for builds, QA serves, and resource allocation. There’s a lot that teams looking to upgrade can learn from their experience.
Key takeaway: Use a Rails version toggle. Nulogy’s team had previously used a long-running branch during an upgrade but decided to use a version toggle for this upgrade. Their upgrade code changes were going to get merged to master constantly.
Kickstarter
Kickstarter’s two biggest internal applications are powered by Rails. One of their engineers working on the big Rails 5 upgrade documented the process of modernizing the 9-year-old legacy application. It’s no surprise that a successful company like Kickstarter has smart tips to share. A few of them include setting a goal timeline and defining success metrics for the upgrade.
They also make the case for incremental upgrades, a strategy we believe in, too. They began the process by trying to release everything but the major version and then upgrading Ruby. By upgrading Ruby as well as Rails, you can reduce gem dependencies that require a specific version of both.
Key takeaway: Define your team (and maybe even name it!) Kickstarter referred to the people working on this upgrade as the #upgraderz and had a dedicated Slack channel and Github team to help them stay organized.
Github
Github spent a year and a half on a big upgrade from Rails 3.2 to 5.2, and documented the process of how they did it for the rest of us to learn from. Besides the upgrade itself, Eileen Uchitelle (who you might know from the Rails core team, or one of her talks at RailsConf) along with an eventual support team of developers, worked to clean up a lot of technical debt in the codebase. This improved the overall health of the project. This team faces a particularly difficult challenge in the sense that the app itself is heavily used – and big.
They utilized a dual boot approach – which we’ve used with success on large client Rails app upgrades, too – to avoid affecting production or using the long-running branch. The lessons that you can learn from this include: upgrading early and often, doing incremental upgrades, and expecting things to break.
It’s reassuring to hear that even a company like Github had challenges modernizing their application – your issues likely aren’t unique!
Key takeaway: Address technical debt often. Eileen advises to “Ensure that the line where your application ends and your framework begins is clear” and get ahead on technical debt when possible. It can be a big bottleneck for a Rails upgrade project.
Bonus content
Robby interviewed Eileen about the Rails upgrade project on our podcast, Maintainable. You can check it out here.
Shopify
Similar to Github, Shopify’s engineering team is working with one of the oldest and biggest Rails applications that you’ll find. They started way back on Rails 0.5 – the first version ever released! This age adds complexity to upgrades. The team that worked on the upgrade documented their preparation, the actual upgrade development work, and the rollout in this post.
At the beginning of the upgrade, the app had over 1,000 failing tests. We’ve dealt with a similar situation during a Rails app upgrade – here’s our strategy for dealing with 1,000 failing specs.
Key takeaway: Keep your gems upgraded. Gems can be a major pain point in Rails upgrades. By keeping an eye on them and upgrading when possible, you’ll save some hassle during upgrades. One strategy is to configure your CircleCI to flag these issues. For us, if we push code and a gem needs to be updated, the build fails. We then add the to-do in our project management tool, JIRA.
GitLab
GitLab is an open-source DevOps platform that helps teams improve their cycle time and collaborate more effectively. Prior to the release of Rails 6, one of the Senior Backend Engineers at GitLab reflected on their team’s Rails 5 upgrade and the challenges encountered.
This article details their CI setup and how their application was able to run on either Rails 4 or Rails 5 depending on an environment variable. They split up their work so that each issue referred to a specific type of error in the CI.
Key takeaway: Cut it into pieces. Gitlab’s initial strategy depended on one big merge request for the Rails 5 upgrade. They eventually decided to split the work into many smaller issues. This allowed multiple people to work collaboratively and still own the work.
Flexport
Flexport is a global freight forwarder built for the digital age. Their software has helped modernize the industry, and they depend upon a Ruby on Rails platform to keep things moving as planned. A member of the Flexport engineering team documented the company’s upgrade from Rails 4.2 to Rails 5, detailing some common errors you might encounter along the way.
This Rails upgrade story doesn’t discuss the team structure or process as much as it breaks down a few errors that their team faced, and the solutions they created.
Key takeaway: Not everything is covered in the upgrade guides. If you encounter an error and you can’t find a good tutorial on how to fix it – you might be the best person to write that tutorial.
A throwback…
Want a blast from the past? Read about how Airbnb upgraded their app from Rails 2.3 to 3.0 way back in 2011. You’ll see from their steps that a lot has changed...but some has stayed the same, too.
Rails upgrades can be tedious, but leaning on the lessons that others have learned can help make the process a little easier.
