This article is part of our Rails Upgrade series. To see more of them, click here.
This article will cover the most important aspects that you need to know to prepare your Ruby on Rails application for working on an upgrade.
Not all applications are good candidates for a Rails upgrade project. We strongly advise against upgrading big applications which are running in production with minimal test coverage.
Make sure that you have at least 80% test coverage before starting the upgrade project. If you don't have a solid test suite (or a dedicated QA team), you will likely find many problems which will force you to roll back the upgrades as soon as they hit production.
We advise all of our clients to follow a Git flow workflow and to actively manage at least two environments: staging and production.
Every change should be code reviewed using pull requests and it should run the entire test suite. Once all checks have passed, changes should be deployed to staging. After your QA team has tested your critical flow in staging, you can deploy the changes to production.
Before working on an upgrade you should make sure that you are running the application with the latest patch version. That way, you make sure that the latest security patches have been installed. On top of that, with more recent versions, you will get a series of deprecation warnings that will be useful in finding out what needs to be done.
Have you ever gotten tangled in dependencies? You need to upgrade dependency A, but that's incompatible with Rails 5.0 because dependency B (which is a dependency of A) is not compatible with that version of ActiveRecord).
Before you start going down the rabbit hole, make sure to check your
Gemfile.lock for incompatibilities. For that, you can use this website: https://railsbump.org/
That will give you an idea of how many dependencies are not compatible with Rails 4, 5, or 6.
To help you switch between your current Rails version and the new one, you can create a dual boot mechanism. The fastest way is to install the handy gem next_rails. You can initialize it by doing
$ gem install next_rails $ next --init
You can then set up two Rails versions in your Gemfile like this:
if next? gem 'rails', '~> 6.0.0' else gem 'rails', '~> 5.2.3' end
Sometimes dependencies are backwards compatible with the current version of Rails. Within the libraries, you will find code that looks like this:
if Rails::VERSION >= 5.1 # does X else # does Y end
If that is the case, then you might be able to just upgrade the dependency using
Now that you have laid the groundwork for you upgrade, it is time to start the work itself. For details on what you specific version upgrade will require, check out the corresponding guide:
- How to upgrade from Rails 2.3 to 3.0
- How to upgrade from Rails 3.0 to 3.1
- How to upgrade from Rails 3.1 to 3.2
- How to upgrade from Rails 3.2 to 4.0
- How to upgrade from Rails 4.0 to 4.1
- How to upgrade from Rails 4.1 to 4.2
- How to upgrade from Rails 4.2 to 5.0
- How to upgrade from Rails 5.0 to 5.1
- How to upgrade from Rails 5.1 to 5.2
- How to upgrade from Rails 5.2 to 6.0