Last Updated on September 2, 2020 by Christopher G Mendla
Whenever you update your Rails version, you should always use Railsdiff.org. The importance of this cannot be overstated. Railsdiff will provide a list of ALL of the changes required to your rails code.
An Overview of updating Rails
Ruby on Rails apps have a Ruby version and a Rails version. The Rails version will need periodic updates for functionality and to resolve emergent security issues. In some cases, Rails updates can require extensive effort and time. It all depends on what has changed between your current and target versions.
Determine your current version
You can determine your current versions with a simple Rails command of ‘rails -v’ which will return the current Rails version:
$ rails -v
Rails 5.1.7
You should also check your gemfile. The Version should be specified and locked to the exact version such as
gem 'rails', '5.1.7'gem 'rails', '-> 5.1.7'Using ‘->’ will allow Rails to update automatically if you run a ‘bundle update’ This can result in updates to Rails without you reviewing Railsdiff.
Determine your Rails target version
Migrating to a newer version of Rails, even for a minor version change, is not something to be taken lightly. In many cases, it would be better to update to the next version of Rails rather than make a major jump in versions. This will result in more branches and PRs but it will also result in a more granular approach to updating. That will make it easier to troubleshoot should you run into problems.
So, in the example above, we are at 5.1.7. The next stable version is 5.2.0. I would not update to any of the betas or rc’s.
Select your target version and click “View Diff”. You will see all of the changes that should be made to cleanly and thoroughly update your version of Rails. In this case, Railsdiff will show 21 files that need to be changed.
Many of the changes are critical to the migration process such as the example below:
Other changes affect the documentation or settings that are commented out. These changes should still be made to keep your code base clean.
The implications of ignoring Railsdiff
I have seen a number of organizations that ignore Railsdiff when migrating Rails to a newer version. The developers simply change what they think needs to be changed to get the migration to work.
I’ve been in a number of interviews as a candidate where I ask about the policy regarding Railsdiff and get a confused or not response.
Migrating rails without addressing all of the code will result in a significant divergence from what should be in the code. At some point this will result in bugs and cause problems for some future updates. The choices at that point would be:
- A major refactoring of the code that would involve locating all of the missed changes and applying them.
- Rebuilding the application with a fresh current copy of Rails. This would be a nightmare for all but the simplest and smallest applications.