How to plan Ruby on Rails upgrade

Table of Contents

Attention! This article might be outdated, refer to latest documentation if solution does not work.

How to plan Ruby on Rails upgrade - cover image

When it is time to upgrade Ruby on Rails? #

One of the main reasons to upgrade is the end of Security Support for the Ruby on Rails version you use. This means all security issues found in the future will not be fixed for your app version. You can check your Ruby on Rails version support here.

Even if your version receives Security Updates you still need to perform an upgrade. Although, it is a much easier process.

Cloud providers’ tech stacks deprecation warnings are another reason to upgrade as soon as possible. To enforce you stay secure and use supportable software, some cloud providers like Heroku deprecate outdated tech stacks and ask you to upgrade.

If none of that is applicable to you, consider the following known wisdom.

Regular upgrades cause regular, but small pain for the development team. Rare upgrades cause rare, but big pain.

Last, but not least. Old versions of Ruby on Rails can make your development team less productive. Framework developers spent years improving it and making it more and more efficient. It is a good idea to benefit from their efforts.

Technical risks #

As you decide to upgrade, pay attention to the following issues, which are considered to be the most common.

Incompatible libraries.
Deprecation of existing code.
Change in existing code behavior.
New infrastructure is required (Ruby, Postgres, Server, etc.).
3rd-party integrations stop working.

Business risks #

Data loss. Major upgrades require database structure changes. This could lead to unexpected data loss.
Solution: backup all the data before an update
Broken functionality. A major upgrade requires every existing feature to be tested.
Solution: write Unit Tests and perform regression testing
Live site downtime.
Solution: warn users and prepare a rollback plan.

Upgrading #

Here is an example flow of the common Ruby on Rails upgrade.

flowchart TB; A[Determine your current stack and versions]-->B[Get familiar with the code] B-->C[Launch the copy of the working app on your dev machine] C-->D{Check the test coverage. Is it enough?} D-- No -->E[Write the minimal valuable amount of Unit tests] E-->D D-- Yes -->F[Choose the target upgrade version] F-- It is not necessary to upgrade to the final version in one go -->G[Read upgrade notes for the next Ruby on Rails version] G-->H[Upgrade infrastructure if required: Ruby, Database, OS] H-->I[Change the Ruby on Rails version in Gemfile and run bundle update] I-->J[Find all the libraries involved in the update] J-->K[Fix all incompatible libraries] K-->L[Fix all deprecated/changed code issues] L-->M[Make sure all Unit tests are passing] M-->N{Is the final target version reached?} N-- No -->F N-- Yes -->O[Go to deploy]

Go Live #

Ready to go live? How to make it safely and without surprises? We suggest following the next approximate plan.

flowchart TB; A[Create testing environment]-->B[Deploy your app to the testing environment] B-->C[Make sure all functions are working properly with regression testing] C-->D[Backup all the production live app data] D-->E[Warn your users about upcoming update] E-->F[Plan the right time for the update] F-- Usually when users are the least affected by possible downtime -->G[Plan the disaster recovery and rollback strategy] G-->H[Perform the production update]

Read further about Upgrading Ruby on Rails apps in our Case studies.