How To Upgrade To Rails 6

I'd like this to be a reasonably detailed overview of how does the upgrade process in Rails look like in general, but with a strong emphasis on Rails 5.2 to 6 upgrade part (RC1 being the latest release). I've already seen a number of great posts describing the list of changes that awaits us in Rails 6, so I will skip this entirely and will focus solely on the upgrade. Keep in mind that even though it's an overview, it is possible that when given a big enough application, the customization on your side may make using e.g. rails app:update impossible.

Should I upgrade yet/things to consider

According to DHH, Rails 6 beta1 was already stable enough to run your projects on it. In fact, in his Rails blog post he writes that Basecamp has already been migrated.

• Basecamp is already running Rails 6.0.0.beta1 in production, and both Shopify and GitHub and surely others will follow close thereafter.
• This isn’t some rickety-shack release.
• DHH

BUT, since there's still no official release yet, you may find that some of the gems you use are not prepared for the upgrade yet. If the gem has Rails version restricted to 5 or lower (or any other dependency for that matter), you may possibly fall into a dependency hell right from the start. If you really don't want this in your life right now, it might be a better choice to wait until most of the gems' creators catch up. Keep in mind though that this might change quickly - I saw big progress in this aspect these past several weeks.

Another thing to consider is how strongly do you feel your app is covered with tests. Having good tests is absolutely crucial for major upgrades. You will change dozens of settings in the process, each of which may change the way the app is working. If you want to know which issue was caused by which change (and I think you want to), you might end up spending obscene amounts of time on manual testing. So if you app is lacking in that department, try to fill in all the gaps of your test suite before progressing.

How to upgrade to Rails 6?

Step 1: Update Ruby to at least version 2.5

Depending on the size of your app and how big of an upgrade it is, during the Ruby upgrade you might encounter a whole bunch of errors or you may see none (OK, that's unlikely). Even when coming from relatively new Ruby versions, I advise you to make these changes incrementally. Ruby releases come in the following pattern: ruby_{MAJOR}_{MINOR}_{TEENY}. I don't think that upgrading by every TEENY version is needed, but incrementing by every other MINOR version (released each Christmas) is a good idea. At minimum, I would split the process into two parts, starting with the version in the middle (between your current and the destination one).

Run your tests after each iteration. Once you've got that working in test/development, repeat the same on the staging server, perform manual testing for any obvious problems and only then go with production. Depending on how much you trust your tests, you may want to give your app a few days before going further with the Rails upgrade.

Step 2: Upgrade Rails to the latest version in 5.2 series (5.2.3 as of writing)

Before starting with Rails 6 upgrade, make sure you're on the latest available Rails 5 version. If you're coming from versions earlier than 5, there are many articles touching the subject, including accounts from Kickstarter, Shopify and GitHub.

Step 3: Update the Gemfile with gem 'rails', github: 'rails/rails' and run bundle update rails

As already mentioned, this might be easier said than done. For mature applications, it is more than likely you will see a long, red list of unresolved dependencies. It usually isn't as bad as it looks - what you see is a result of the chain reaction which might have been caused by a mere single gem. The list is not displayed in any particular order (that I know of at least). You will get a bunch of Bundler could not find compatible versions for gem XXX errors, but usually, only a few of those include a conflicting gem. In my experience there are usually two kinds of culprits:

• rails related gems (rails. railties, actionpack, activesupport etc.) limited to versions < 6
• gems with an upgrade limited to minor versions by using the \\\\\\\~> operator which is why I tend to look for these on the list first. In order to fix them, I usually have to manipulate a combination of project's Gemfile and Gemfile.lock, along with gems' .gemspecs and sometimes Rakefiles. One of the projects I bundled (experimentally) for the needs of this article was content-data-admin from alphagov. In their case, the list had over 70 lines, but only one dependency was blocking the bundle from progressing (in that case it was actionview from the govuk_publishing_components gem (screenshot below).

Whether the gem will work fine with the dependency unlocked is, of course, a different matter, but most of the gems should have no issues working with Rails 6 if they already worked with 5. With the previous versions (Rails 4 and 5) you could have used Ready4Rails app to check whether the gem is ready to work with a particular Rails version - currently, there's no mention of Rails 6, but this might change by the time you read this.

Bumping the Rails version might fix the problem, although this comes with an obvious disadvantage of having to either fork each of these gems or finding someone who's already done it for you. I am not aware of any workarounds here, so bear that in mind before going further. In my biggest upgrade out of 231 gems I had bundled, 6 had to be forked and upgraded manually.

Step 4: Run rails app:update from terminal

rails app:update leads you step by step by adding the new config settings to your app. It's an interactive process which is seemingly easy but can lead to some unexpected problems if enough caution is not taken. I recommend you to run the diff tool (d) for every suggested file change to be fully aware of the change extent.

I doubt you will want to overwrite some of the files it will suggest (e.g. routes or I18n files). You have two options here:

• Before choosing y/n, select (m) and merge the files with a tool of your choice
• Use y for every file, then using merge tool/IDE go file by file and see what changes were implemented. Combine the new settings with the old, custom ones. Personally, I prefer the second approach - I get to decide in what order the files are updated, having better control and view of things overall. Note: both this and the next step can be tiresome. Give yourself a favor and approach each setting individually. It is extremely easy to miss/add/remove one little thing, which will eventually lead to hours of debugging that could have been otherwise avoided. If you get lost in what's new and what's old, this site* can be helpful. And since you're on it, check the default configs from previous upgrades as well (if the project started before Rails 5), this is a good moment to have them set correctly.

As the comment on the main page states - the tool shows the difference between the newly generated application in different Rails versions. It does not show all the commits implemented between the versions internally.

Step 5: Uncomment defaults in new_framework_defaults_6_0.rb

As of now (Rails 6.0 RC1), the comment at the top of the file is slightly misleading. It advises to "flip defaults", where in fact you should simply uncomment the flags. It goes back to Rails 5.0, where after updating from Rails 4.2 the flags were uncommented and set to false by default, and only then were supposed to be switched to true. This is not the case in Rails 6 - here, the flags already have the correct values. The comment should be fixed in the final release though. All flags with their defaults are listed and described in the Configuring Rails Applications guide, although the comments in the file are already descriptive and should be enough to let you make the right decision (to uncomment or not).

Step 6: Add missing gems and bundle

Each major Rails version comes with a slightly different set of gems. Unfortunately, the rails app:update command will not help in that aspect, so without manual changes, the app may break without some dependencies in place. There are many ways you can approach this - using RailsDiff is one of them (see: Gemfile).

Step 7: Run migrations

Should be required only if ActiveStorage is installed.

Step 8: Go through official upgrading Rails guide and release notes

Implement changes from the first link if needed. Skim through the second link to search for any potential breaking changes that might be specific to your app. If you have good test coverage, most of the problems will come up while running the test suite anyway.

Step 9: Run the tests, suppress deprecations

Right after the bigger update (especially on legacy projects), deprecation warnings can take the majority of output you will get from the tests. My advice is to fix them as quickly as possible. You could hide them with ActiveSupport::Deprecation.silenced = true, but you will have to tackle the problem at some point anyway, so why not do this now? This part isn't too hard and is very rewarding at the same time - making the output clean really feels like progress.

Step 10: Run the tests, fix the failing ones

It's impossible to cover enough material here to be helpful to any significant number of readers. It seems that lots of people already started trying out Rails 6 upgrade, as most of the issues I encountered were already reported/asked about on boards. Some of them have been even fixed in the meantime, which is showing that the upgrade will get only easier as time passes.

Step 11: Perform manual tests

As much as I'd love to believe that automatic testing is all we need, after getting all green, I like to open the page on the server and check manually if anything was overlooked.

Step 12: Push to staging

Before going live, set up or use existing staging to test the app in an environment looking closer to production. If possible, get other people to test it with you.

Step 13: Push to production

Wrap up

The Rails 6 RC1 version isn't probably going to change much before the final release so now is a good time to seriously consider an upgrade. My feeling is that the procedure was much easier than for example from 4.2 to 5.0, especially if the app started on one of the 5.X versions. As always, having your dependencies up to date and good test coverage should very much ease the whole process. First drafts of this article were written right after the Beta1 was released and in the span of the past weeks I can see the difference in community preparedness for making the leap. Hopefully, before you read this most of the problems will be already solved.