Originally posted on Hint's blog.

Following up on my best practices post, I have a prime example of one common issue that surfaces when upgrading a Rails app.

I decided to spike on upgrading a small internal app to Rails 6.0.0.rc1. The test suite is green on Rails 5.2.3 and Ruby 2.6.2, so I bumped the Rails version in the Gemfile.

source '<https://rubygems.org>'
git_source(:github) { |repo| "<https://github.com/#{repo}.git>" }

ruby '2.6.2'

gem 'rails', '6.0.0.rc1'

In the terminal, I ran bundle update rails and it updated without issue (I mentioned this is a small app, right?). Even on small apps, this should make you raise an eyebrow.

Skeptically, I ran the test suite.

Errors all the way down.

An error occurred while loading ./spec/services/step_processor_spec.rb.
Failure/Error: require File.expand_path('../../config/environment', __FILE__)

TypeError:
  Rails::SourceAnnotationExtractor is not a class/module
# /gems/gems/haml-rails-1.0.0/lib/haml-rails.rb:49:in `block in <class:Railtie>'
# ...more output...

Finished in 0.00027 seconds (files took 1.41 seconds to load)
0 examples, 0 failures, 17 errors occurred outside of examples

Based on the error, let's take a look at haml-rails and SourceAnnotationExtractor in Rails to see what changed and if there is a newer version of haml-rails.

But wait. You may ask: "Why not try upgrading the gem and move on?". Taking the time to understand the root cause of a problem provides confidence in the solution and clear direction to resolve broader symptoms throughout the codebase.

Taking the time to understand the root cause of a problem provides confidence in the solution and clear direction to resolve broader symptoms throughout the codebase.

Here is line 49 in lib/haml-rails.rb:

SourceAnnotationExtractor::Annotation.register_extensions('haml') do |tag|

Sure enough, there is a change in Rails 6 that moves SourceAnnotationExtractor to Rails::SourceAnnotationExtractor (PR #32065). The top-level class has been deprecated, but the deprecation warning does not apply to the sub-classes which raise the TypeError.

Knowing the source of the error, we can check if there is a newer version of haml-rails compatible with Rails 6. Again, you will find value by not just upgrading the gem, but understanding the changes in the newer versions. With haml-rails, there is a newer version that has a fix for the issue. By bumping up to that version, I'm able to run the test suite without errors and get back to the upgrade at hand.

Schedule a quick call with me to see how our expertise can keep your team delivering features during your Rails upgrade.