Big Picture: Practical Steps for Upgrading the Ruby on Rails Version in a Small to Medium-Sized App 🚀

Upgrading a Rails app to the latest version can feel overwhelming.

I had no idea where to start when I tackled it for the first time.

Deprecation warnings, gem conflicts, and the infamous “it works locally but not on production 🫥” surprises can make the process seem like a maze of headaches.

But don’t worry. With a clear plan and a step-by-step approach, it doesn’t have to be daunting. After upgrading my app from Rails 5 to Rails 7 and learning through mistakes, I would like to share the steps I’ve found most helpful 🚀

---

Step 0: Have a Degradation Test Ready

Before upgrading rails, it’s crucial to have a degradation test in place. A degradation test is a combination of automated tests (like unit, integration, or system tests) and manual tests that ensure the critical functionality of your application remains intact after changes. Essentially, it’s your safety net to catch breaking issues early.

If you already have a robust set of tests for major upgrades, great! If you don’t, it’s probably not realistic to start creating a comprehensive automated test suite just for the rails upgrade—it would be a monumental task. Instead, focus on creating comprehensive manual tests for your app’s core functionality 👀 Identify key features that must work without fail and document step-by-step processes to verify them.

With these tests ready, you'll feel more assured about handling the upgrade without worrying about breaking key features. While creating them might seem tedious now, they’ll save you time and headaches during this and future upgrades.

---

Step 1: Read the Official Migration Guide

This is one of the most important steps 🔥 in upgrading your Rails version—it sets the foundation for a smooth and successful migration.

Before diving in, bookmark the official Rails upgrade guide. This is your go-to resource for version-specific advice, highlighting key changes that could impact your app.

Take a moment to grab a coffee ☕️ and read through the documentation. As you go, create a checklist of the changes you’ll need to tackle, so you can work through them step by step. (Personally, I also create a list of what I don’t understand so that I can systematically research later.)

At first, it might feel overwhelming, especially if it’s your first time upgrading Rails—there’s a lot of information, and some parts may be unfamiliar. But that’s actually a good thing! 💡 Rails goes the extra mile to provide comprehensive guides to help you, something you don’t always get with other libraries. 😅

You may need to do some additional research along the way, but this effort pays off 👍 By understanding the changes and their impact on your codebase, you’ll be better equipped to troubleshoot issues, update your tests, and confidently make the necessary updates later.

---

Step 2: Fix Deprecation Warnings

When upgrading rails, one of the first things I always deal with is DEPRECATION WARNING. These warnings are rails' way of notifying you that certain features or methods you're using are outdated and will be removed in future versions.

While these warnings don’t necessarily break your app right away, ignoring them could cause issues when you eventually upgrade to the next rails version.

I’ve written an extensive post on the subject that walks you through the process in detail.

Check it out here: Rails and Ruby Deprecation Warnings: Stop Ignoring, Start Fixing.

---

Step 3: Update Gems

Upgrading rails almost always requires updating your gems to resolve dependency conflicts. While starting with bundle outdated to identify outdated gems might seem like a logical first step, it can be unrealistic for older apps with numerous gems or complex configurations.

A practical approach I often follow is to create a separate test branch for the upgrade. First, I update the Rails version in the Gemfile to the desired version, then run bundle update rails to begin the upgrade process. At this point, you'll likely encounter dependency conflicts, but that's expected 😌

The point here is to identify gems that have dependency conflicts so that you can systematically address these conflicts by updating gems one at a time in a different brach, ensuring each update works seamlessly with your current app’s setup. I believe this method keeps the process manageable while maintaining stability throughout the upgrade.

Here’s a step-by-step approach to manage gem updates effectively:

1. Create a Test Branch
   Start by creating a new branch for the gem updates to keep your main branch stable. This allows you to experiment without affecting the production codebase.

2. Run bundle update
   Execute bundle update rails . This step will likely trigger dependency conflicts. This is part of the process so it is okay 👍

3. Make a List of Conflicting Gems
   Review the errors carefully and compile a list of conflicting gems. This will give you a clear roadmap for addressing each issue systematically and at the right time.

4. Update Gems Incrementally in Separate Branches
   Update each gem from the list in a separate branch. In some cases, certain gems can only be updated after upgrading your rails version. Make a note of these gems 📝, and remember to revisit later.

   For a more detailed guide on updating gems effectively, check out my post:

   How to Keep Your Ruby Gems Up-to-Date Without the Stress.

This systematic approach ensures a smoother process, keeping your app stable while aligning with Rails’ latest requirements.

---

Step 4 : Update gem rails version

Once you’ve updated all the necessary gems and resolved dependency issues, it’s time to update your rails version. Run bundle update rails to ensure your application is using the latest rails version specified in your Gemfile.

---

Step 5 : Run rails app:update

Once you’ve successfully updated your rails version, the next step is to run the rails app:update command. This command is a useful tool that helps create new files and update existing ones to align with the latest rails version. However, you’ll also need to adjust the code to fit your specific configuration and needs.

Before running this command, I strongly recommend visiting RailsDiff to review the changes between your current Rails version and the one you’re upgrading to. This step helps you prepare for the updates and better understand the adjustments being made.

One important thing to note is that running this command might update the load_defaults version in your app in config/applicatin.rb. ⚠️You DO NOT have to update the version of load_defaults when upgrading rails version 🙆‍♂️ To better understand how to manage and update load_defaults, refer to my blog:

Demystifying Rails load_defaults: Mastering Configuration Updates.

---

Step 6 : Update Existing Code

After upgrading rails, it's possible that your application contains code that relies on now-deprecated behaviors. (Carefully review the deprecation warnings you encountered earlier, as they often pinpoint specific areas of your code that need attention.) Use the checklist you created in Step 1 and incrementally make change ✅

In addition, some gem upgrades may only be possible after upgrading rails itself. For these gems, you might find that their behaviors have changed, requiring you to update how your application interacts with them. Use the list from Step 3 and ensure their corresponding code adjustments are thoroughly tested after the rails upgrade is complete.

To streamline this process, I recommend you to use your test suite to catch regressions early. Running your tests after each change can help identify areas where functionality breaks, allowing you to address issues incrementally. Don't forget to also manually test complex workflows or areas that aren’t well-covered by automated tests.

---

Step 7: Test, Test, Test 😎

Testing is the keystone of any successful rails upgrade—your last line of defense against unexpected issues and your best assurance that your app is production-ready.

By this point, you’ve already laid a solid foundation: you’ve followed the upgrade guide, fixed deprecation warnings, and updated your gems. Now, it’s time to validate everything. This isn’t just about running tests—it’s about systematically uncovering and addressing any lingering issues. Let’s break it down. 🚦

1. Run Your Automated Test Suite

Automated tests can quickly identify broken functionality caused by the upgrade. Again, fix issues incrementally and rerun tests after each fix to confirm that the problem has been resolved.

2. Conduct Manual Testing

Automated tests alone may not be sufficient, especially for complex workflows, user interactions, or edge cases. This is where your manual degradation tests from Step 0 come into play. Focus on critical user-facing features like payment, form submissions, and reports—anything that directly impacts core functionalities.

3. Test in a Staging Environment

Before merging into production, deploy your upgraded Rails app to a staging environment that mirrors production. This step helps catch environment-specific issues that might not appear locally.

4. Plan for Post-Deployment Testing

Even with the most thorough testing, surprises can happen in production. Be prepared to monitor logs, errors, and user reports closely after deployment. Having a rollback plan ready can be a lifesaver in case something goes wrong.

Testing is the final hurdle in your Rails upgrade journey, and while it might feel tedious, it’s worth the effort. Think of it as your safety net that ensures your users experience a smooth, reliable application.

With automated tests passing, manual workflows verified, and staging tests completed, you’ll be ready to confidently deploy your upgraded Rails app. 🚀

---

Wrapping up

Upgrading a Rails app may seem overwhelming at first, but with a clear plan, it becomes a rewarding process. By preparing degradation tests, addressing deprecation warnings, and updating gems incrementally, you can minimize risks and maintain stability. Thorough testing—both automated and manual—ensures a smooth transition to the new version. Each upgrade strengthens your app’s foundation and boosts your confidence as a developer. Good luck 🚀