Upgrading Ruby - Steps to follow

Upgrading Ruby sounds scary, and there are plenty of stories about people losing weeks and weeks of work to what feels like relatively small upgrades. In this post, we will talk through some of the steps you should take, and some of the specifics involved in performing a Ruby upgrade.

I will get some self promotion out of the way early. If you’ve been tasked with doing a large upgrade, and even after reading this post you still feel very much out of your depth, get in touch, we can either help coach you through this or take on the work ourselves.

High-level steps to upgrade Ruby

Here are the high-level steps to upgrade Ruby, even if you’ve been doing this a long time, I’d not suggest skipping over any one of them.

Check your current Ruby version

Before upgrading, check the current version of Ruby that you are using by running the command ruby -v. This will give you the current version number. This is important for a future step.

It is good practice to have this version documented somewhere; lots of projects will use .ruby-version (we will talk about this later), but having it in the README is useful to anyone.

Decide on your target version

Determine which version of Ruby you want to upgrade to. You can check the latest stable version of Ruby on the official Ruby releases page.

Our advice is to try and just upgrade to the next stable version of Ruby, there will be fewer headaches, and it is generally easier to turn back. Even if ultimately you want to go up several releases, do it one release at a time.

For example, if you were on Ruby 2.7.8 and wanted to go to Ruby 3.2.2, we would suggest;

• Ruby 3.0.6
• Ruby 3.1.4
• Ruby 3.2.2

If you were on an older point release of Ruby 2.7, such as Ruby 2.7.6, you should upgrade to Ruby 2.7.8 first.

This sounds like extra work, but it will help you in the long run.

Find the differences between your current and desired Ruby version

By using the above releases page, you can check what was changed in a given release. Click on Release notes; here are the release notes for Ruby 3.2.2. From there, you can click on “GitHub releases”, which will take you to a GitHub page detailing the changes. Here we can see lots of bug fixes and some security fixes, there don’t appear to be any breaking changes.

You don’t need to be an expert in the Ruby language after reading these, you just want to get a rough idea about things you may need to test or change once you’ve updated.

Install the new version of Ruby

Use your preferred installation method to install the new version of Ruby. If you use a version manager like rbenv or RVM, you can use their respective commands to install the new version.

We have a section called places to update Ruby which talks about some specifics depending on your setup.

Update Bundler

If you are using Bundler to manage your application dependencies (you should!), update it by running the command gem install bundler. This will ensure that your Gemfile.lock file is updated with the correct gem versions.

bundle install will make sure everything is up to date.

Test your application

After upgrading Ruby and updating your gems, it is essential to test your application to ensure it works as expected. Run your test suite and verify that all tests pass.

Run the application and perform some smoke tests, even if you believe you have adequate test coverage.

Address any issues

If you encounter any issues during testing, investigate and fix them. You may need to update your code or dependencies to be compatible with the new version of Ruby.

By only updating to the next smallest version of Ruby, you should hopefully only be changing a small handful of things at a time.

It is important to re-run your tests and your smoke tests after making these changes. We do not want to change any business logic as a result of our Ruby upgrade.

Commit your changes

Once you have verified that your application works correctly, commit your changes and push them to your version control system. Let it also run whatever builds and tests you have, then you are ready to deploy.

Deploying will very much depend on your individual setup, but we would advise deploying to a staging environment first and making sure everything works as you would expect, and then you’re ready to deploy to production.

Places to update Ruby

On a standard Ruby on Rails app, there are a few common places where you may need to specify your new Ruby version. I will explain each in more detail, but they are

• Your .ruby-version file
• Your Gemfile
• Your build file (e.g. GitHub actions, etc.)
• Your Dockerfile

What is the .ruby-version file?

.ruby-version is a small text file placed in the root directory of a Ruby project and is recognised by many Ruby version managers, such as rbenv and RVM (RVM is what we use). It is also used by some hosting environments, such as Heroku.

When a Ruby version manager detects the .ruby-version file in a project directory, it sets the specified Ruby version as the default version for that project. This ensures that the project uses the correct version of Ruby and avoids conflicts with other projects or system-wide installations of Ruby.

The .ruby-version file typically contains the version number of Ruby to be used, for example, 3.0.6 or 3.1.4.

If you wanted to update your version of Ruby, you would change this file, and in the terminal move away from the directory and move back in. Your Ruby version manager will see the change and either switch or ask you to install the new version of Ruby.

Changing the Gemfile for a Ruby upgrade

As we cover in “what is a Gemfile” you can also specify your preferred version of Ruby in the Gemfile. To update you would change the version

ruby "3.0.6"

Then re-run bundle install.

Changing your build file for a Ruby upgrade

If you run any automated build or testing along with your project (you should) then you will have a file that specifies things like what languages you use and how to build the project.

Make sure that any Ruby versions listed in these files get updated.

Here is an example of a Github action which uses Ruby. We could update the ruby-version here. I say “could” because setup-ruby can read your .ruby-version file, meaning you have one less place to upgrade.

uses: ruby/setup-ruby@v1
with:
  ruby-version: '3.2'

Updating Ruby in your Dockerfile for a Ruby upgrade

If you use Docker for local development you will need to upgrade Ruby in your Dockerfile.

Your Dockerfile, much like other build files, will contain what version of languages you need. This will need to be updated to reflect your new Ruby version. It will often be a simple line like below.

FROM ruby:3.2.0

Frequently asked Ruby upgrade questions

Here are some quickfire questions and answers based on conversations I’ve been a part of or seen online.

• How do I update Ruby on a Mac? - Everything in this article was tested on a Mac, the specific commands you need to run will be dictated by how you installed Ruby onto your system. Most people use a version manager, which I’ve mentioned above.
• How do I find out my Ruby version on a Mac? - ruby -v should work on any operating system, including the Mac.
• How do I find all the Ruby versions? - You can find all of the changelogs since Ruby 2.6.8 on Github
• Should I also upgrade my gems when I upgrade Ruby? - You might have to depending on the versions of Ruby supported by your gem, where possible, try and keep your Ruby upgrade about upgrading Ruby.
• How do I switch Ruby versions on a Mac? - Use RVM or RBenv, which let you quickly jump between Ruby versions. For your own mental health I would try and keep projects as similar as possible.
• What should I do when I see a “your ruby version is x but your gemfile specified y” error? - This is what happens when you change one variable but not the other. Normally the fix is to update the ruby x line in your Gemfile. Or if the Gemfile has the right version, make sure your Ruby version manager is using the correct version of Ruby.
• How do I update Ruby on Ubuntu? - Whilst everything in this article was tested on a Mac, the entire process should also work fine on Ubuntu. The specific commands you need to run will be dictated by how you installed Ruby onto your system. Most people use a version manager, which I’ve mentioned above.
• Should I always upgrade to the latest version of Ruby? - Not necessarily, you should always try to be using a version that is receiving security and other upgrades, but that doesn’t always mean being on the latest version as soon as you can.
• How do I update RBenv? - If you installed rbenv with homebrew, which is the recommended way, then brew update rbenv.
• How do I update RVM? - rvm get stable will install the most stable version.

If you have a question about upgrading Ruby that hasn’t been covered by this post, please get in touch.