Rails upgrades for beginners

Keeping your Rails applications up to date with the latest version of Rails and its supporting gems is best done in small increments, and frequently.

In the real world, you might be asked to upgrade a Rails app by two major versions. There are nuances to every major release and the best place to find this information is in the official Rails Guides. The general process however is quite methodical, diagrammable even! Clearing your console of deprecation warnings and changing test output from red to green is as pleasant as it sounds.

Before you start, check the test coverage of the application. If the unit tests do not provide good coverage or key features are not integration tested, add ‘tedious manual testing’ after the automated testing step or write some tests first.

Here is the promised diagram:

Flowchart outlining the process of upgrading the rails version of an app

That is it! Here are some appendices all about versions of everything.

Appendix A – Gem version conventions

PATCH 0.0.x level changes for implementation level detail changes, such as small bug fixes

MINOR 0.x.0 level changes for any backwards compatible API changes, such as new functionality/features
MAJOR x.0.0 level changes for backwards incompatible API changes, such as changes that will break existing users code if they update
Lesson: Skip ahead to the highest patch version but increment by minor version to catch deprecations as they pop up.

Appendix B – Gem version specifiers

When you include a gem in your Gemfile, you can specify a gem version; Most of the version specifiers, like >= 1.0, are self-explanatory. This is the oddball:

~> which is best explained by example:
~> 2.0.3 is identical to >= 2.0.3 and < 2.1
~> 2.1 is identical to >= 2.1 and < 3.0
The squiggly specifier is great because it makes running bundle update less dangerous. Still, try to update you gems one at a time.

Appendix C – Ruby versions

The Ruby language is constantly being enhanced, and versions become unsupported with time. Ideally you will have your project running on the latest stable Ruby version, but gems may use Ruby functions that have since been deprecated. Basically, increase the Ruby version until a necessary gem cannot run on a higher version. Here is a list of minimum Ruby versions for Rails apps:

Rails 5 requires Ruby 2.2.2 or newer.
Rails 4 prefers Ruby 2.0 and requires 1.9.3 or newer.
Rails 3.2.x is the last branch to support Ruby 1.8.7.
Rails 3 and above require Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially. You should upgrade as early as possible.
Here is the source and here are all the Ruby releases.