Chapter 1: Getting Started FastRuby.

io

Chapters
Chapter 1: Getting Started 1
Chapter 2: Deprecation Warnings 2
Chapter 3: From Rails 2.3 to 3.0 3
Chapter 4: From Rails 3.0 to 3.1 4
Chapter 5: From Rails 3.1 to 3.2 5
Chapter 6: From Rails 3.2 to 4.0 6
Chapter 7: From Rails 4.0 to 4.1 7
Chapter 8: From Rails 4.1 to 4.2 8
Chapter 9: From Rails 4.2 to 5.0 9
Chapter 10: From Rails 5.0 to 5.1 10
Chapter 11: From Rails 5.1 to 5.2 11
Chapter 12: From Rails 5.2 to 6.0 12
Chapter 13: From Rails 6.0 to 6.1 13
Chapter 14: Next Steps 14
Chapter 15: Need Help? 15

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 1: Getting Started

Creating new products with Rails is easy, but upgrading
an application can become a huge project. If you fall
behind the latest releases, deprecations can pile up
and turn a simple Rails upgrade project into a major
headache.

Even if you keep your application code up to date, some

of your dependencies may fall behind and become major
blockers.

At FastRuby.io, we have upgraded over 80 applications,

from small MVPs to huge monoliths, helping companies
who don't have time to work through their technical
debt.

In this book we will use that experience to guide you

through the steps you will need to follow to upgrade
from Rails 2.3 to Rails 6.0.

Caveats
Not all applications are good candidates for a Rails
upgrade project. We strongly advise against upgrading
big applications which are running in production with
minimal test coverage.

You don't want your end users to test your upgrades.

You want to make sure that you have at least 80% test
coverage before starting the upgrade project.

4th Edition
Chapter 1: Getting Started FastRuby.io

If you don't have a solid test suite, you will likely

find many problems which will force you to roll back
the upgrades as soon as they hit production.

We have worked with companies that have a team of

quality assurance experts. This is the only exception
to this rule. If you have a dedicated QA team that
tests your application's critical path, then you can
start working on your upgrade.

We advise all of our clients to follow a Git flow

workflow and to actively manage at least two
environments: staging and production.

Every change should be code reviewed using pull

requests and it should run the entire test suite. Once
all checks have passed, changes should get deployed to
staging. After your QA team has tested your critical
flow in staging, you should deploy the changes to
production.

The Guide
The advice in this guide comes from working on many
upgrade projects and what we have learned in the
process. We recommend that you follow these
instructions as much as possible to ship a smooth
upgrade.

Patch Versions

4th Edition
Chapter 1: Getting Started FastRuby.io

The first step is to make sure that you are running the
application with the latest patch version. That way,
you make sure that the latest security patches have
been installed. On top of that, with more recent
versions, you will get a series of deprecation warnings
that will be useful in finding out what needs to be
done.

Dependencies
Have you ever gone down the rabbit hole? In order to
upgrade Rails, you need to upgrade dependency A (which
is not compatible with Rails 5.0 because dependency B
which is a dependency of A is not compatible with that
version of ActiveRecord)

Before you start going down the rabbit hole, make sure
to check your Gemfile.lock for incompatibilities. For
that, you can this website: https://railsbump.org/

That will give you an idea of how many dependencies are

not compatible with Rails 4, 5, or 6.

Backwards compatible changes

For every change that you work on, you should ask
yourself: Is this change backwards compatible? If not,
could I make this change backwards compatible?

The idea behind this is to submit many small pull

requests to your application before you submit the
version bump pull request. There are many pros to this
approach:

4th Edition
Chapter 1: Getting Started FastRuby.io

You will reduce the mass of code within the version

bump pull request
You will deploy these smaller pull requests to
staging and production as soon as possible
You will get feedback from users as soon as possible
(We know that even the best test suites won't cover
all the scenarios a user in production might run
into)
You will communicate to your team members that now
this is the way to do things, so that they stop
submitting pull requests using old APIs

Add dual boot for the Rails

version
To help you switch between your current Rails version
and the new one, you can create a dual boot mechanism.
The fastest way is to install the handy gem next_rails.
You can initialize it doing

$ gem install next_rails

$ next --init

Dual booting is a helpful strategy that you can use in

all environments:

development: you can quickly switch between one

version to the other and debug unexpected behavior.
test: you can run two versions of the test suite
(one with the current version, another with the
target version).

4th Edition
Chapter 1: Getting Started FastRuby.io

production: you can gradually deploy the changes to

production, that way you can deliver a small
percentage at a time.

There is one caveat with dual booting though: If your

test suite takes three hours to run, for example, it
will double your test suite run time to 6 hours. In
that case it might not be a great idea to run both
versions every time.

Using dual boot

You can set up two Rails versions in your Gemfile like
this:

if next?
gem 'rails', '~> 6.0.0'
else
gem 'rails', '~> 5.2.3'
end

Sometimes dependencies are backwards compatible with

the current version of Rails. Within the libraries, you
will find code that looks like this:

if Rails::VERSION >= 5.1

# does X
else
# does Y
end

If that is the case, then you might be able to just

upgrade the dependency using bundle update .

4th Edition
Chapter 1: Getting Started FastRuby.io

If the dependency does not have backwards compatible

code, you can use different versions of other gems, not
only Rails:

if next?
gem "dep", "~> 1.2.3"
else
gem "dep", "~> 0.9"
end

In cases when you can't just update the gem's version,

you have four alternatives:

Find an alternative library

Write your own code to address the library’s
function and remove the library dependency
Submit a contribution to the library to add support
for the version of Rails that you need
If the contribution is never merged, you can
consider starting a new fork of the library

Branch, Fix, Merge

Create the Rails upgrade branch and
submit a Pull request
After adjusting all the dependencies in the application
for both Rails versions, you can create the rails-next-

version branch with all the dual boot code and open a PR
that will target master. The idea is that from now on,
every PR that you create and can't be merged to master

4th Edition
Chapter 1: Getting Started FastRuby.io

directly, will target the rails-next-version branch. As

you can imagine, this big PR won't be merged until all
necessary changes are done.

This helps you deliver small testable changes during

the upgrade and keep a stable branch that can be used
as base.

Create new branches for each update

that is needed
For every story that you're working on, create a new
pull request. If the change is not backwards
compatible, the PR will target the rails-next-version

branch, if it is, it will target the master branch.

At this point, if you run the test suite using the new
version of Rails, it's highly likely that a bunch of
tests will fail. It's time to address them and open a
pull request for each one or for each root cause,
depending of the complexity of the changes.

When addressing these failures, we recommend that you

create one story per root cause. There may be 100s of
failures for one root cause. So you should start
addressing the root causes that fix the most tests.

Sometimes there will be little snippets of code that

you can write to make the changes backwards compatible,
they are called rails upgrade shims. You can use shims
to send pull requests to master and deploy them to
production as soon as possible.

Making sure that everything works

4th Edition
Chapter 1: Getting Started FastRuby.io

After the test suite passes, you can do QA with someone

from the client's team or by their own QA team if
possible.

Merge the rails upgrade branch

If all changes are done and you have everything working
in the rails-next-version branch, you can finally take a
breath! It's time to merge the rails upgrade PR and
celebrate.

Deployments
Once you have submitted and deployed all the backwards
compatible changes you could think of and gotten rid of
all deprecation warnings, it is time to deploy.

In this phase, you must have a way to track your errors

(Honeybadger, Sentry, Airbrake, or similar) which will
help you find any new exceptions in your app. You can
safely assume that any new exception was produced by
the version bump.

After deployment, you should analyze all new exceptions

and determine whether they were caused by the Rails
upgrade or not. If exceptions are happening in a
critical path of the application, you should roll back
your change and work on a patch.

At this point, you want to iron out any issues that

were not discovered during the previous phase. You will
need to iterate and deploy as many times as necessary
to ship the version bump.

4th Edition
Chapter 1: Getting Started FastRuby.io

Once no new errors are reported you can safely assume

that the upgrade was successful!

How to read this book

You should skip to the chapter related to your current
Rails version. If you are running Rails 4.2 in
production, you can start here:

Chapter 9: From Rails 4.2 to 5.0

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 3: Deprecation
Warnings
Deprecation warnings are a common thing in our
industry. They are warnings that notify us that a
specific feature (e.g. a method) will be removed soon
(usually in the next minor or major version) and should
be replaced with something else. Features are
deprecated rather than immediately removed, in order to
provide backward compatibility (a solution that works
in both the current and the future version), and to
give programmers time to implement the code in a way
that follows the new standard.

Finding deprecation warnings

There are a few different ways to find deprecation
warnings in your application.

If you have good test coverage, you can run the whole
test suite and look at the logs that were generated. If
you are using a CI service (like CircleCI or Travis CI)
you can easily see the logs once the build finishes
running. Otherwise, if you run the tests locally, you
can look at the output in the console or in the
log/test.log file.

In Rails, all deprecation warnings start with DEPRECATION

WARNING: , so you can search for that string in your

logs.

4th Edition
Chapter 1: Getting Started FastRuby.io

When it comes to production, the easiest way to

discover deprecation warnings is by using a monitoring
tool (like Honeybadger or Airbrake).

This is not standard behavior, but it is quite useful.

In order to send deprecation warnings to one of these
tools, you would have to do something like this:

# config/environments/production.rb

config.active_support.deprecation = :notify

# config/initializers/deprecation_warnings.rb

ActiveSupport::Notifications
.subscribe('deprecation.rails') do |name, start, finish, id, payload|
# Example if you use Honeybadger:
Honeybadger.notify(
error_class: "deprecation_warning",
error_message: payload[:message],
backtrace: payload[:callstack]
)
end

See page for more details about

ActiveSupport::Notifications.subscribe :
https://guides.rubyonrails.org/active_support_instrumen
tation.html#subscribing-to-an-event

You can also set config.active_support.deprecation to :log

and look at the log/production.log file, but it won't be

as straightforward as the first option. Depending on
the traffic your application gets, your production.log

might have a lot of noise.

Tracking deprecation warnings

4th Edition
Chapter 1: Getting Started FastRuby.io

Once you have all the deprecation warnings (or most of

them) from your application, it is a good idea to track
them as if they were issues. You can use the project
management tool of your preference and create a story
in the backlog for each root cause of the deprecation
warnings. That way it makes things a lot easier when it
comes to code review and organization in general.

Also, it is a good idea to prioritize the deprecation

warnings based on the frequency that they occur. That
way, you make sure you first work on the ones that fix
the largest amount of errors for the next Rails
version.

Fixing deprecation warnings

At this point you can grab a story from the top of the
backlog and work on it. Most of the deprecation
warnings are very clear about what needs to be updated.
If that's not the case, a quick google search will
provide more answers. Usually you will have to apply
the same fix across many files, so make sure you search
for all occurrences in the project folder.

Keep in mind that sometimes deprecation warnings can

also happen inside gems. That usually happens when the
gem has rails as a dependency and uses deprecated code
in it. If that's the case you should consider upgrading
that gem.

Once the changes are done, run the appropriate specs or

manually test the parts that were modified to make sure
that everything works normally.

4th Edition
Chapter 1: Getting Started FastRuby.io

After that, you can create a new pull request and move
on to the next deprecation warning on your backlog.

Best Practices
In order to not accumulate deprecation warnings in your
application, it is a good practice to treat them as
errors. You can easily configure that in your
config/environments/test.rb and config/environments/development.rb

files:

config.active_support.deprecation = :raise

Avoiding Regressions

After you fix a deprecation warning in the project, you

want to make sure that nobody introduces that
deprecated code again.

Rubocop

If you are using Rubocop, you can write a cop to check

for deprecated code. Take a look at
Lint/DeprecatedClassMethods for some references on
that.

Disallowed deprecations in ActiveSupport

Rails 6.1 will come with a new feature to disallow

deprecations. You'll be able to configure the
deprecation warnings that you fixed as disallowed. If a
disallowed deprecation is introduced, it will be
treated as a failure and raise an exception in
development and test. In production it will log the
deprecation as an error.

4th Edition
Chapter 1: Getting Started FastRuby.io

# config/environments/test.rb

ActiveSupport::Deprecation.disallowed_behavior = [:raise]
ActiveSupport::Deprecation.disallowed_warnings = [
"uniq",
:uniq,
/(uniq)!?/,
]

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 3: From Rails 2.3

to 3.0
In this chapter we will be covering the most important
aspects of updating your Ruby on Rails application from
version 2.3 to 3.0.

1. Considerations
2. Ruby version
3. Tools
4. XSS protection
5. Config files
6. Gems
7. Deprecations
Active Record
Action Mailer
Metal
Railties
8. Next steps

1. Considerations
Before beginning with the upgrade process, we recommend
that each version of your Rails app has the latest
patch version before moving to the next major/minor
version. For example, in order to follow this article,
your Rails version should be at 2.3.18 before updating
to Rails 3.0.20.

2. Ruby version

4th Edition
Chapter 1: Getting Started FastRuby.io

Rails 3.0 requires Ruby 1.8.7 or higher, but no more

than 1.9.3. If you want to use Ruby 1.9.x, we recommend
you skip directly to 1.9.3. Also Ruby 1.9.1 is not
usable because it has segmentation faults on Rails 3.0.
That means that the compatible Ruby versions for Rails
3.0 are 1.8.7, 1.9.2, or 1.9.3.

3. Tools
There is an official plugin that helps the upgrade
process. You just need to install the script by doing
script/plugin install git://github.com/rails/rails_upgrade.git and
then run rake rails:upgrade:check to see most of the files
you need to upgrade in your application. It also
provides some other generators to upgrade specific
areas in your app like routes or gems.

Sometimes it's also useful to check which files changed

between two specific versions of Rails. Fortunately
Rails Diff makes that easy.

4. XSS protection
In this version, Rails automatically adds XSS
protection in order to escape any content, so you will
probably need to update your templates according to
this. Luckily there is an official plugin for this. We
recommend you take a look at it.

5. Config files
Rails 3 introduces the concept of an Application
object. An application object holds all the specific

4th Edition
Chapter 1: Getting Started FastRuby.io

application configurations and is similar to the

current config/environment.rb from Rails 2.3. The
application object is defined in config/application.rb.
You should move most of the configuration that you had
in config/environment.rb there.

In terms of routes, there are a couple of changes that

you need to apply to your routes.rb file. For example:

# Rails 2.3 way:

ActionController::Routing::Routes.draw do |map|
map.resources :products
end

# Rails 3.0 way:

AppName::Application.routes do
resources :products
end

Check out this article to read more in depth about this

topic.

6. Gems
Bundler is the default way to manage Gem dependencies
in Rails 3 applications. You will need to add a Gemfile
in the root of your app, define all your gems there,
and then get rid of the config.gem statements.

4th Edition
Chapter 1: Getting Started FastRuby.io

# Before:
config.gem 'aws-sdk', :version => '1.0.0' # (config/environment.rb)

config.gem 'pry', :version => ['>= 0.6.0', '< 0.7.0'] # (config/developm

# Now:
(Gemfile)

gem 'aws-sdk', '1.0.0'

group :development do
gem 'pry', '~> 0.6.0'
end

Remember that if you installed the plugin mentioned in

Step 3, you can run rake rails:upgrade:gems . This task will
extract your config.gem calls and generate code that
you can put in your Gemfile.

7. Deprecations
There are a bunch of deprecations that happen during
this version:

Active Record
The method to define a named scope is now called
scope instead of named_scope .

In scope methods, you no longer pass the conditions

as a hash:

4th Edition
Chapter 1: Getting Started FastRuby.io

# Before:
named_scope :active, :conditions => ["active = ?", true]

# Now:
scope :active, where("active = ?", true)

save(false) is deprecated, so you should use

save(:validate => false) .

I18n error messages for Active Record should be

changed from :en.activerecord.errors.template to
:en.errors.template .

model.errors.on is deprecated in favor of model.errors[]

There is a new syntax for presence validations:

# Before:
validates_presence_of :email

# Now:
validates :email, presence: true

ActiveRecord::Base.colorize_logging and
config.active_record.colorize_logging are deprecated in
favor of Rails::LogSubscriber.colorize_logging or
config.colorize_logging .

Action Mailer
:charset , :content_type , :mime_version ,
:implicit_parts_order are all deprecated in favor of
ActionMailer.default :key => value style declarations.
Mailer dynamic create_method_name and deliver_method_name

are deprecated, just call method_name which now

4th Edition
Chapter 1: Getting Started FastRuby.io

returns a Mail::Message object.

# Before:
message = UserMailer.create_welcome_email(user)
UserMailer.deliver(message)

or

UserMailer.deliver_welcome_email(user)

# Now:
UserMailer.welcome_email(user).deliver

template_root is deprecated, pass options to a render

call inside a proc from the format.mime_type method
inside the mail generation block.
The body method to define instance variables is
deprecated ( body {:ivar => value} ), just declare
instance variables in the method directly and they
will be available in the view.

# Before:
def welcome_email(user)
...
body {:user => user, :url => "https://fastruby.io"}
end

# Now:
def welcome_email(user)
...
@user = user
@url = "https://fastruby.io"
end

Mailers should now be in app/mailers instead of

app/models.

4th Edition
Chapter 1: Getting Started FastRuby.io

Metal
Since Rails 3 is closer to Rack, the Metal abstraction
is no longer needed.

This is the official explanation of what you need to do

to update your existing Metals:

If your metal behaves like a middleware, add it to

the middleware stack via config.middleware.use. You
can use methods on the middleware stack to control
exactly where it should go.
If it behaves like a Rack endpoint, you can link to
it in the router. This will result in more optimal
routing time, and allows you to remove code in your
endpoint that matches specific URLs in favor of the
more powerful handling in the router itself.

For the future, you can use ActionController::Metal to

get a very fast controller with the ability to opt-in
to specific controller features without paying the
penalty of the full controller stack.

Railties
Railties deprecates the following constants during this
version:

RAILS_ROOT in favor of Rails.root

RAILS_ENV in favor of Rails.env

RAILS_DEFAULT_LOGGER in favor of Rails.logger

Also, PLUGIN/rails/tasks and PLUGIN/tasks are no longer

loaded all tasks, now must be in lib/tasks .

4th Edition
Chapter 1: Getting Started FastRuby.io

# Before:
vendor/plugins/ombulabs_patches/tasks/s3_backup.rake

# Now:
lib/tasks/ombulabs_patches/s3_backup.rake

8. Next steps
At this point your application should be properly
running in Rails 3.0. In the next chapter we will talk
about the migration from Rails 3.0 to Rails 3.1.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 4: From Rails 3.0

to 3.1
In this chapter we will be covering the most important
aspects of upgrading your Ruby on Rails application
from version 3.0 to 3.1.

1. Considerations
2. Ruby version
3. Tools
4. Config files
5. jQuery
6. Asset Pipeline
7. Next steps

1. Considerations
Before beginning with the upgrade process, we recommend
that each version of your Rails app has the latest
patch version before moving to the next major/minor
version. For example, in order to follow this article,
your Rails version should be at 3.0.20 before updating
to Rails 3.1.12

2. Ruby version
Rails 3.1 requires Ruby 1.8.7 or higher, but no more
than 1.9.3. If you want to use Ruby 1.9.x, we recommend
you skip directly to 1.9.3. Also Ruby 1.9.1 is not

4th Edition
Chapter 1: Getting Started FastRuby.io

usable because it has segmentation faults on Rails 3.1.

That means that the compatible Ruby versions for Rails
3.1 are 1.8.7, 1.9.2, or 1.9.3. Keep in mind that the
next Rails version (3.2) will be the last one that
supports Ruby 1.8.7 and 1.9.2.

3. Tools
Rails 3.1 comes with a generator that helps the upgrade
process. You just need to run rake rails:update to see a
guide that details how to upgrade your application.

Sometimes it's also useful to check which files changed

between two specific versions of Rails. Fortunately
Rails Diff makes that easy.

4. Config files
You should remove any references to
ActionView::Base.debug_rjs in your project.

# (config/environments/development.rb)

config.action_view.debug_rjs = true

If you want to wrap parameters into a nested hash, add

a config/initializers/wrap_parameters.rb file with the
following content:

4th Edition
Chapter 1: Getting Started FastRuby.io

# Be sure to restart your server when you modify this file.

# This file contains settings for ActionController::ParamsWrapper which
# is enabled by default.

# Enable parameter wrapping for JSON. You can disable this by setting :f
ActiveSupport.on_load(:action_controller) do
wrap_parameters :format => [:json]
end

# Disable root element in JSON by default.

ActiveSupport.on_load(:active_record) do
self.include_root_in_json = false
end

This file is included by default in all new

applications.

5. jQuery
jQuery is the default JavaScript library that comes
with Rails 3.1.

To add this you need to include the jquery-rails gem in

your Gemfile

gem 'jquery-rails'

And then include the libraries in your

app/assets/javascripts/application.js

//= require jquery

//= require jquery_ujs

Now you can get rid of your jQuery assets like

jquery.js or jquery.min.js .

4th Edition
Chapter 1: Getting Started FastRuby.io

6. Asset Pipeline
The Rails Asset Pipeline is an optional feature in
Rails 3.1, but we recommend including it to take
advantage of its capabilities. In order to include it,
you should apply the following changes:

Add to your Gemfile :

group :assets do
gem 'sass-rails', "~> 3.1.5"
gem 'coffee-rails', "~> 3.1.1"
gem 'uglifier', ">= 1.0.3"
end

Update your config/application.rb

config.assets.enabled = true
config.assets.version = '1.0'

# Defaults to '/assets'
config.assets.prefix = '/asset-files'

Update your config/environments/development.rb

# Do not compress assets

config.assets.compress = false

# Expands the lines which load the assets

config.assets.debug = true

Update your config/environments/production.rb

4th Edition
Chapter 1: Getting Started FastRuby.io

# Compress JavaScripts and CSS

config.assets.compress = true

# Don't fallback to assets pipeline if a precompiled asset is missed

config.assets.compile = false

# Generate digests for assets URLs

config.assets.digest = true

# Defaults to Rails.root.join("public/assets")
# config.assets.manifest = YOUR_PATH

# Precompile additional assets (application.js, application.css, and all

# config.assets.precompile = %w( admin.js admin.css )

Update your config/environments/test.rb

# Configure static asset server for tests with Cache-Control for perform
config.serve_static_assets = true
config.static_cache_control = "public, max-age=3600"

7. Next steps
After you get your application properly running in
Rails 3.1, you will probably want to keep working on
this Rails upgrade journey.

In the next chapter we will take you from Rails 3.1 to

Rails 3.2.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 5: From Rails 3.1

to 3.2
In this chapter we will be covering the most important
aspects of updating your Ruby on Rails application from
version 3.1 to 3.2.

1. Considerations
2. Ruby version
3. Tools
4. Config files
5. Gemfile
6. Deprecations
7. Next steps

1. Considerations
Before beginning with the upgrade process, we recommend
that each version of your Rails app has the latest
patch version before moving to the next major/minor
version. For example, in order to follow this article,
your Rails version should be at 3.1.12 before updating
to Rails 3.2.22

2. Ruby version
Depending on which patch version of Rails 3.2 you are
using, the Ruby versions that you can use will change.
Since we recommend that you always use the latest patch

4th Edition
Chapter 1: Getting Started FastRuby.io

version, we will focus this article on Rails 3.2.22.

You can use any Ruby version between 1.8.7 and 2.2. As
always, we recommend using the latest version to avoid
any bugs or vulnerabilities.

3. Tools
Rails 3.2 comes with a generator that helps you to
update the configuration files. The rake rails:update

generator will identify every configuration file in

your application that differs from a new Rails
application. When it detects a conflict, it will offer
to overwrite your file. Keep in mind that many of your
files will be different because you’ve made changes
from a default new Rails application. When the
generator offers to overwrite a file, enter a d in
order to review the differences.

Sometimes it's also useful to check which files changed

between two specific versions of Rails. Fortunately
Rails Diff makes that easy.

4. Config files
There are a few settings that you need to add to your
environment filters.

Add to config/environments/development.rb

4th Edition
Chapter 1: Getting Started FastRuby.io

# Raise exception on mass assignment protection for Active Record models

config.active_record.mass_assignment_sanitizer = :strict

# Log the query plan for queries taking more than this (works
# with SQLite, MySQL, and PostgreSQL)
config.active_record.auto_explain_threshold_in_seconds = 0.5

Add to config/environments/test.rb

# Raise exception on mass assignment protection for Active Record models

config.active_record.mass_assignment_sanitizer = :strict

5. Gemfile
You should update a couple of gems inside your assets
group:

gem "rails", "~> 3.2.0"

group :assets do
gem 'sass-rails', '~> 3.2.6'
gem 'coffee-rails', '~> 3.2.2'
gem 'uglifier', '>= 1.0.3'
end

6. Deprecations
Rails 3.2 deprecates vendor/plugins , and it's the last
Rails version that supports it. If your plan is to
migrate to Rails 4 in the future, you can start
replacing any plugins by extracting them to gems and

4th Edition
Chapter 1: Getting Started FastRuby.io

adding them to your Gemfile , or you can move them into

lib/my_plugin/* . We cover this topic in depth in our
Rails 4.0 upgrade guide.

7. Next steps
After you get your application properly running in
Rails 3.2, you will probably want to keep working on
this Rails upgrade journey.

In the next chapter we will take you from Rails 3.2 to

Rails 4.0.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 6: From Rails 3.2

to 4.0
In this chapter we will be covering the most important
aspects of updating your Ruby on Rails application from
version 3.2 to 4.0

1. Ruby version
2. Gems
3. Config files (config/)
4. Application code
i. Models (app/models/)
ii. Controllers (app/controllers/)
5. Tests
6. Miscellaneous
7. Upgrading gems
8. Next steps

1. Ruby version
Rails 3.2.x is the last version to support Ruby 1.8.7.
If you're using Ruby 1.8.7, you'll need to upgrade to
Ruby 1.9.3 or newer. The Ruby upgrade is not covered in
this guide, but check out this guide for more details
on that.

2. Gems

4th Edition
Chapter 1: Getting Started FastRuby.io

You can add the aptly named rails4_upgrade gem to your

Rails 3 project's Gemfile and find which gems you'll
need to update:

➜ myproject git:(develop) ✗ bundle exec rake rails4:check

** GEM COMPATIBILITY CHECK **

+------------------------------------------+----------------------------
| Dependency Path | Rails Requirement
+------------------------------------------+----------------------------
| devise 2.1.4 | railties ~> 3.1
| devise-encryptable 0.2.0 -> devise 2.1.4 | railties ~> 3.1
| friendly_id 4.0.10.1 | activerecord < 4.0, >= 3.0
| strong_parameters 0.2.3 | actionpack ~> 3.0
| strong_parameters 0.2.3 | activemodel ~> 3.0
| strong_parameters 0.2.3 | activesupport ~> 3.0
| strong_parameters 0.2.3 | railties ~> 3.0
+------------------------------------------+----------------------------

Instead of going through your currently bundled gems or

Gemfile.lock manually, you get a report of the gems you
need to upgrade. We will delve further into upgrading
gems in Section 7.

3. Config files
Rails includes the rails:update task. You can use this
task as a guideline as explained thoroughly in this
post. It will help you get rid of unnecessary code or
monkey patches in your config files and initializers,
especially if your Rails 3 app was running on Rails 2.

As an alternative, check out RailsDiff, which provides

an overview of the changes in a basic Rails app between
3.2 and 4.0 (or any other source/target versions).

4th Edition
Chapter 1: Getting Started FastRuby.io

If you're feeling adventurous, you can give this script

a try. It attempts to apply this git patch (similar to
the patch shown on RailsDiff) to your Rails app to
migrate from 3.2 to 4.0. However, I don't recommend
this for complex or mature apps, as there will be
plenty of conflicts.

4. Application code

a. Models
All dynamic finder methods except for .find_by_... are
deprecated:

# before:
Authentication.find_all_by_provider_and_uid(provider, uid)

# after:
Authentication.where(provider: provider, uid: uid)

You can regain usage of these finders by adding the gem

activerecord-deprecated_finders

ActiveRecord scopes now need a lambda:

4th Edition
Chapter 1: Getting Started FastRuby.io

# before:
default_scope where(deleted_at: nil)

# after:
default_scope { where(deleted_at: nil) }

# before:
has_many :posts, order: 'position'

# after:
has_many :posts, -> { order('position') }

(Friendly reminder: beware when using default_scope)

Protected attributes is deprecated, but you can still

add the protected_attributes gem. However, since the
Rails core team dropped its support as of Rails 5.0,
you should begin migrating your models to Strong
Parameters anyway.

To do so, you will need to remove calls to

attr_accessible from your models, and add a new method to
your model's controller with a name like user_params or
your_model_params :

class UsersController < ApplicationController

def user_params
params.require(:user).permit(:name, :email)
end
end

Finally, change (most) references to params[:user] to

user_params in your controller's actions. If the
reference is for an update or a creation, like
user.update_attributes(params[:user]) , change it to
user.update_attributes(user_params) . This new method permits

4th Edition
Chapter 1: Getting Started FastRuby.io

using the name and email attributes of the user model

and disallows writing any other attribute the user
model may have (like id ).

ActiveRecord Observers were removed from the Rails

4.0 codebase and extracted into a gem. You can
regain usage by adding the gem to your Gemfile:

gem 'rails-observers' # https://github.com/rails/rails-observers

As an alternative, you can take a look at the wisper

gem, or Rails' Concerns (which were added in Rails 4.0)
for a slightly different approach.

ActiveResource was removed and extracted into its

own gem:

gem 'active_resource' # https://github.com/rails/activeresource

b. Controllers
ActionController Sweeper was extracted into the
rails-observers gem, you can regain usage by adding
the gem to your Gemfile:

gem 'rails-observers' # https://github.com/rails/rails-observers

Action caching was extracted into its own gem, so if

you're using this feature through either:

caches_page :public

4th Edition
Chapter 1: Getting Started FastRuby.io

or:

caches_action :index, :show

You will need to add the gem:

gem 'actionpack-action_caching' # https://github.com/rails/actionpack-ac

5. Tests
From Ruby 1.9.x onwards, you have to include the test-

unit gem in your Gemfile as it was removed from the

standard lib. As an alternative, migrate to Minitest ,
RSpec or your favorite test framework.

6. Miscellaneous
Routes now require you to specify the request
method, so you no longer can rely on the catch-all
default.

# change:
match '/home' => 'home#index'

# to:
match '/home' => 'home#index', via: :get

# or:
get '/home' => 'home#index'

4th Edition
Chapter 1: Getting Started FastRuby.io

Rails 4.0 dropped support for plugins, so you'll need

to replace them with gems, either by searching for the
project on RubyGems/Github, or by moving the plugin to
your lib directory and requiring it from somewhere
within your Rails app.

7. Upgrading gems
If you're using any non-standard gems, you're probably
going to enjoy this section.

Some gems stopped being maintained before Rails 4 was

released, as was the case with CanCan, a well known
authorization library. After many open pull requests
were left unmerged, CanCanCan was released. It is a
community driven effort to have a semi-official fork of
CanCan. It serves as a drop-in replacement for people
who want to use CanCan after upgrading to Rails 4.

This gem should help you in the Rails 4.0 upgrade:

https://github.com/alindeman/rails4_upgrade

You can add it to your Rails 3 project and use a Rake

task that will help you with the upgrade:

4th Edition
Chapter 1: Getting Started FastRuby.io

➜ myproject git:(develop) ✗ bundle exec rake rails4:check

** GEM COMPATIBILITY CHECK **

+------------------------------------------+----------------------------
| Dependency Path | Rails Requirement
+------------------------------------------+----------------------------
| devise 2.1.4 | railties ~> 3.1
| devise-encryptable 0.2.0 -> devise 2.1.4 | railties ~> 3.1
| friendly_id 4.0.10.1 | activerecord < 4.0, >= 3.0
| strong_parameters 0.2.3 | actionpack ~> 3.0
| strong_parameters 0.2.3 | activemodel ~> 3.0
| strong_parameters 0.2.3 | activesupport ~> 3.0
| strong_parameters 0.2.3 | railties ~> 3.0
+------------------------------------------+----------------------------

Now instead of going through your currently bundled

gems or Gemfile.lock manually, you get a report of what
gems you need to upgrade.

For an overview of your outdated gems, there's also

bundle outdated , which you can run on any project:

4th Edition
Chapter 1: Getting Started FastRuby.io

➜ myproject git:(develop) ✗ bundle outdated

Fetching gem metadata from http://rubygems.org/........
Fetching version metadata from http://rubygems.org/...
Fetching dependency metadata from http://rubygems.org/..
Resolving dependencies..........................................

Outdated gems included in the bundle:

* aasm (newest 4.11.0, installed 3.0.26, requested ~> 3.0.22)
* activemerchant (newest 1.59.0, installed 1.47.0, requested ~> 1.47.0
* acts_as_list (newest 0.7.4, installed 0.7.2, requested ~> 0.7.2)
* airbrake (newest 5.4.1, installed 4.1.0, requested ~> 4.1.0)
* awesome_nested_set (newest 3.1.1, installed 2.1.6, requested ~> 2.1.
* aws-sdk (newest 2.3.17, installed 1.64.0, requested ~> 1.64.0)
* byebug (newest 9.0.5, installed 5.0.0, requested ~> 5.0.0)
* cancancan (newest 1.15.0, installed 1.13.1, requested ~> 1.10)
* capistrano (newest 3.5.0, installed 3.4.0, requested ~> 3.0)
* capistrano-rails (newest 1.1.7, installed 1.1.5, requested ~> 1.1)
* capybara (newest 2.8.0.dev 59d21b5, installed 2.6.0.dev 3723805)
* capybara-webkit (newest 1.11.1, installed 1.7.1)
* codeclimate-test-reporter (newest 0.6.0, installed 0.4.8)
* compass (newest 1.0.3, installed 0.12.7)
* compass-rails (newest 3.0.2, installed 2.0.0)
* cucumber (newest 2.4.0, installed 1.3.20, requested ~> 1.3.10)
* cucumber-rails (newest 1.4.3, installed 1.4.2, requested ~> 1.4.0)
* database_cleaner (newest 1.5.3, installed 1.5.1, requested ~> 1.5.1)
* devise (newest 4.1.1, installed 2.1.4, requested ~> 2.1.0)
* ...

8. Next steps
After you get your application properly running in
Rails 4.0, you will probably want to keep working on
this Rails upgrade journey. In the next chapter we will
talk about the migration from Rails 4.0 to Rails 4.1.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 7: From Rails 4.0

to 4.1
In this chapter we will cover the most important
aspects of updating your Ruby on Rails application from
version 4.0 to 4.1.

1. Ruby version
2. Gems
3. Config files (config/)
4. Application code
i. Callbacks
ii. ActiveRecord
5. Tests
6. Miscellaneous
7. Next steps

1. Ruby version
Rails 4.1 requires Ruby 1.9.3 or later. Ruby 1.8.7
support was dropped in Rails 4.0, so you should already
be running 1.9.3 or later. For Rails 4.1, Ruby 2.0 (or
newer) is preferred according to the official upgrade
guide.

2. Gems

4th Edition
Chapter 1: Getting Started FastRuby.io

If your application relies on MultiJSON , you will need

to add the gem to your Gemfile ( gem 'multi_json' ) if it's
not already there, since it was removed from Rails 4.1.

Alternatively, stop using MultiJSON and migrate your

application to use to_json and JSON.parse .

3. Config files
Rails includes the rails:update task. You can use this
task as a guideline as explained thoroughly in this
post.

As an alternative, check out RailsDiff, which provides

an overview of the changes in a basic Rails app between
4.0 and 4.1 (or any other source/target versions).

4. Application code
a. Callbacks
Return from callbacks is no longer allowed:

Before:

before_save { return false }

After:

before_save { false }

See: https://github.com/rails/rails/pull/13271

4th Edition
Chapter 1: Getting Started FastRuby.io

b. ActiveRecord
Removal of deprecated finders:

activerecord-deprecated_finders
(https://github.com/rails/activerecord-
deprecated_finders) was removed as a dependency from
Rails 4.1. You will need to migrate away from dynamic
finders.

Before:

User.find_all_by_email(email)

After:

User.where(email: email)

Before:

User.find_last_by_email(email)

After:

User.where(email: email).last

Also:

1. scoped_by_... should become where(...)

2. find_or_initialize_by_... should become

find_or_initialize_by(...)

3. find_or_create_by_... should become find_or_create_by(...)

If you can't afford to upgrade the finders now, then

add the gem back into the Gemfile :

4th Edition
Chapter 1: Getting Started FastRuby.io

gem 'activerecord-deprecated_finders'

Default scopes are now chained to other scopes:

If you thought default scopes on models could be

confusing, there's even another (un?)expected twist to
it:

class User < ActiveRecord::Base

default_scope { where active: true }
scope :inactive, -> { where active: false }

# ...
end

# Rails < 4.1

> User.all
SELECT "users".* FROM "users" WHERE "users"."active" = 'true'

> User.inactive
SELECT "users".* FROM "users" WHERE "users"."active" = 'false'

# Rails >= 4.1:

> User.all
SELECT "users".* FROM "users" WHERE "users"."active" = 'true'

> User.inactive
SELECT "users".* FROM "users" WHERE "users"."active" = 'true'
AND "users"."active" = 'false'

If you depended on this behavior, you will need to work

around it using unscoped , unscope or the new rewhere

method (source).

No more mutable methods on ActiveRecord relations:

4th Edition
Chapter 1: Getting Started FastRuby.io

ActiveRecord::Relation no longer has access to mutator

methods like #map! , #delete_if or #compact! . If you need
to use them, you will need to convert the Relation into
an Array by calling #to_a first.

Before:

Project.where(title: 'Rails Upgrade').compact!

After:

projects = Project.where(name: 'Rails Upgrade').to_a

projects.compact!

Implicit joins are removed:

Before Rails 4.1, if you had this code:

Post.includes(:comments).where("comments.title = 'foo'")

ActiveRecord 4.0 would know to join posts and comments

in the executed SQL, and it would work just fine.

However, Rails shouldn't have to be smart and parse

your where with a regular expression to figure out
what tables you want to join, since it leads to bugs
(for example:
https://github.com/rails/rails/issues/9712).

To fix this problem, you need to use an explicit join:

Post.joins(:comments).where("comments.title = 'foo'")

4th Edition
Chapter 1: Getting Started FastRuby.io

Unless your intention was to actually eager load the

post's comments. In that case, you can use the
following syntax:

Post.eager_load(:comments).where("comments.title = 'foo'")

Or:

Post.includes(:comments).where("comments.title = 'foo'").references(:com

Both are equivalent and produce the same SQL.

For a more in depth explanation of the differences

between joins , includes , references , eager_load and even
preload , check out this post.

Finally, if you get this deprecation warning:

DEPRECATION WARNING: Implicit join references were removed with Rails 4.

Just remove config.active_record.disable_implicit_join_references

from your config files.

5. Tests
CSRF protection now covers GET requests with JS
responses:

If your tests hit JS URLs, you'll need to use xhr

instead of get :

Before:

4th Edition
Chapter 1: Getting Started FastRuby.io

post :create, format: :js

After:

xhr :post, :create, format: :js

See: https://github.com/rails/rails/pull/13345

6. Miscellaneous
Flash message keys are strings now:

If you were using the flash hash or its keys and

expected symbols, you will need to use strings now:

Before:

flash.to_hash.except(:notify)

After:

flash.to_hash.except("notify")

7. Next steps
If you successfully followed all of these steps, you
should now be running Rails 4.1! In the next chapter we
will talk about the migration from Rails 4.1 to Rails
4.2.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 8: From Rails 4.1

to 4.2
In this chapter we will cover the most important
aspects of updating your Ruby on Rails application from
version 4.1 to 4.2.

1. Ruby version
2. Gems
3. Config files (config/)
4. Application code
i. ActiveRecord
ii. ActionMailer
5. Miscellaneous
6. Next steps

1. Ruby version
Rails 4.2 requires Ruby 1.9.3 or later, and Ruby 2.0
(or newer) is preferred according to the official
upgrade guide.

2. Gems
If you're using RSpec 2, you'll need to migrate to
RSpec 3, since RSpec 2 doesn't officially support Rails
4.2. To make this process easier, you can update to
RSpec 2.99, which will print a bunch of deprecation

4th Edition
Chapter 1: Getting Started FastRuby.io

warnings at the end of the test run, and you'll need to

fix these before updating to RSpec 3. For more
information, check out their official upgrade guide.

You can also use the awesome Transpec to automate the

RSpec 2 to 3 upgrade process.

Once you're on Rails 4.2, you will be able to remove

the Timecop gem if you're using it, and replace it with
new test helper methods travel , travel_to and
travel_back . See: TimeHelpers.

3. Config files
Rails includes the rails:update task. You can use this
task as a guideline as explained thoroughly in this
post.

As an alternative, check out RailsDiff, which provides

an overview of the changes in a basic Rails app between
4.1.x and 4.2.x (or any other source/target versions).

After upgrading to Rails 4.2 for an application that

needs to run in development on port 80, I came across
an unexpected problem due to a change in Rack. Rails
now listens on localhost instead of 0.0.0.0 . You will
run into the same problem in the case that you need to
access your Rails server from a different machine. To
work around it, you need to start your server by
binding to 0.0.0.0 by using:

rails server -b 0.0.0.0 -p 80

4th Edition
Chapter 1: Getting Started FastRuby.io

Alternatively, you can try the solution here to avoid

providing -b 0.0.0.0 when you start the server. If
you're using Foreman and run into this problem, you can
edit your Procfile 's web entry so that it reads:

web: bundle exec rails s -b 0.0.0.0

4. Application code
a. ActiveRecord
ActiveRecord <= 4.2 suppresses exceptions raised in the
after_commit and after_rollback callbacks by default. They
are rescued and printed on the log, and they don't
propagate. You can opt in to raising these exceptions
now by adding the following configuration:

config.active_record.raise_in_transactional_callbacks = true

Starting from ActiveRecord 5.0, these exceptions are

always raised regardless of this setting, so you should
opt in to it and update your code accordingly.

See: https://github.com/rails/rails/pull/16537

If you pass an object to #find , you will now run into

the following deprecation warning:

DEPRECATION WARNING: You are passing an instance of ActiveRecord::Base t

Please pass the id of the object by calling `.id`.

You will need to change your .find calls to pass an id

instead of an object.

4th Edition
Chapter 1: Getting Started FastRuby.io

Before:

Comment.find(comment)

After:

Comment.find(comment.id)

The same goes for #exists? calls, if you pass an object

as a parameter for it, you will need to provide an id
instead.

b. ActionMailer
deliver and deliver! are deprecated, in favor of
deliver_now and deliver_now! .

Before:

NotificationMailer.daily_summary(user).deliver

After:

NotificationMailer.daily_summary(user).deliver_now

5. Miscellaneous
respond_with and the class-level respond_to were removed
from Rails 4.2 and moved to the responders gem.

If you're using these in your controllers, you will

need to add:

4th Edition
Chapter 1: Getting Started FastRuby.io

gem 'responders', '~> 2.0'

to your Gemfile .

The HTML sanitizer was rewritten to use the more secure

Loofah gem. As a result, your expected sanitized output
might be slightly different for some inputs. If you
experience problems with it, you can restore the
behavior by adding:

gem 'rails-deprecated_sanitizer'

to your Gemfile . It will only be supported for Rails

4.2, so it's recommended that you do not do this and
stick with the new default HTML sanitizer.

6. Next steps
If you successfully followed all of these steps, you
should now be running Rails 4.2! In the next chapter we
will take you from Rails 4.2 to 5.0.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 9: From Rails 4.2

to 5.0
In this chapter we will cover the the most important
aspects of updating your Ruby on Rails application from
version 4.2 to 5.0.

1. Ruby version
2. Gems
3. Config files (config/)
4. Application code
i. ActiveRecord
ii. Controllers
5. Testing
6. Next steps

1. Ruby version
Rails 5.0 requires Ruby 2.2.2 or later.

This Ruby upgrade shouldn't generate any problems.

However, if you run into this exception in your test
suite:

cannot load such file -- test/unit/assertions (Load Error)

then you'll need to add the following gem to your

Gemfile :

gem 'test-unit'

4th Edition
Chapter 1: Getting Started FastRuby.io

2. Gems
It's recommended that you check your Gemfile against
RailsBump to ensure all your gems are compatible with
Rails 5. As of the release of this blog post, there are
only a few gems which don't support Rails 5 yet. This
is more of a problem when you're upgrading early on.

If any of the gems are missing on RailsBump, you'll

need to manually check the Github page for the project
to find out its status. In case you own the gem, you'll
need to make sure it works on Rails 5 or update it.

3. Config files
Rails includes the rails app:update task. You can use this
task as a guideline as explained thoroughly in this
post.

As an alternative, check out RailsDiff, which provides

an overview of the changes in a basic Rails app between
4.2.x and 5.0.x (or any other source/target versions).

4. Application code
a. ActiveRecord
ActiveRecord models will now inherit from
ApplicationRecord by default instead of
ActiveRecord::Base. You should create an
application_record.rb file under app/models </span>with:

4th Edition
Chapter 1: Getting Started FastRuby.io

class ApplicationRecord < ActiveRecord::Base

self.abstract_class = true
end

And then update all of your models to inherit from

ApplicationRecord instead of ActiveRecord::Base . The only
class that inherits from ActiveRecord::Base will be
ApplicationRecord .

belongs_to associations are now required by default.

This means that if the association doesn't exist for
a model when saving it, an error will be triggered.
You can turn this feature off for an association by
using optional: true :

belongs_to :user, optional: true

b. Controllers
If you're not already using strong parameters, and
still rely on protected_attributes , you should migrate
your application to strong parameters before attempting
to upgrade to Rails 5.0. protected_attributes is no longer
supported on Rails 5.0.

A few months ago we worked on a project to attempt to

automate the strong parameters migration process, and
this resulted in the gem RailsUpgrader. It's in a beta
state, but you can try using it if you have too many
models, or at least as a guide for a WIP branch.

There are still efforts being made to keep

protected_attributes alive though, like the
protected_attributes_continued gem. I would strongly

4th Edition
Chapter 1: Getting Started FastRuby.io

recommend against using it since its support is

limited, and it won't work in future Rails versions.

Parameters now behave differently, they no longer

inherit from HashWithIndifferentAccess . Some methods (e.g.:
fetch , slice , except ) you may now be calling on
params will no longer work. You will need to permit the
parameters, call o_h , and only then will you be able
to run the Hash methods you need on them.

For more information:

https://github.com/rails/rails/pull/20868

5. Testing
One of the most common methods in controller tests,
assigns , has been extracted from Rails and moved to the
rails-controller-testing gem. If you wish to continue using
it (and assert_template ), you'll need to add it to your
Gemfile :

gem 'rails-controller-testing'

Instead of using ActionDispatch::Http::UploadedFile to test

uploads, you'll need to update those tests to use
Rack::Test::UploadedFile .

6. Next steps
If you successfully followed all of these steps, you
should now be running Rails 5.0! In the next chapter we
will discuss API changes in the Rails 5.2 release.

4th Edition
Chapter 1: Getting Started FastRuby.io

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 10: From Rails 5.0

to 5.1
In this chapter we will cover the most important
aspects that you need to know to get your Ruby on Rails
application from Rails 5.0 to 5.1.

1. Ruby version
2. Gems
3. Config files
4. Application code
i. ActiveRecord
ii. Controllers
5. Testing
6. Next steps

1. Ruby version
Like Rails 5.0, Rails 5.1 requires Ruby 2.2.2 or later.

2. Gems
Make sure the gems you use are compatible with Rails
5.1, you can check this using RailsBump. If a gem is
missing on RailsBump, you'll need to manually check
the Github page for the project to find out its
status. In case you own the gem, you'll need to make
sure it supports Rails 5.1 and if it doesn't, update
it.

4th Edition
Chapter 1: Getting Started FastRuby.io

3. Config files
Rails includes the rails app:update task. You can use
this task as a guideline as explained thoroughly in
this post.

As an alternative, check out RailsDiff, which provides

an overview of the changes in a basic Rails app between
5.0.x and 5.1.x (or any other source/target versions).
Always target your upgrade to the latest patch version
(e.g: 5.1.6 instead of 5.1.0).

Some assets configuration changes you'll have to do on

your config/environments/{development, test, production}.rb files
are:

Before:

config.serve_static_files = false
config.static_cache_control = "public, max-age=3600"

After:

config.public_file_server.enabled = false
config.public_file_server.headers = "public, max-age=3600"

4. Application code
4.1. ActiveRecord
The raise_in_transactional_callbacks option is now
removed. It was already deprecated and covered in a
previous upgrade.

4th Edition
Chapter 1: Getting Started FastRuby.io

Also removed was use_transactional_fixtures , which was

replaced by use_transactional_tests .

ActiveRecord::Base#uniq was removed, it was deprecated

in Rails 5.0 and has been replaced by #distinct .
Check out https://github.com/rails/rails/pull/20198
for the discussion.

4.2. Controllers
Before Rails 5.1, conditions in filters could be
invoked using strings. They now have to be symbols:

Before

before_action :authenticate_user!, unless: 'has_project_guest_id'

After:

before_action :authenticate_user!, unless: :has_project_guest_id

All *_filter methods are now called *_action :

These methods were actually already deprecated in Rails

5.0, and Rails 5.1 removes support for *_filter usage,
so you should be using *_action .

Before:

skip_before_filter :authenticate_user!
before_filter :authenticate_user!
after_filter :do_something

After:

4th Edition
Chapter 1: Getting Started FastRuby.io

skip_before_action :authenticate_user!
before_action :authenticate_user!
after_action :do_something

5. Testing
Parameters in controller tests now need a params

key:

Rails 5.0 had already deprecated this behavior, and

Rails 5.1 drops support for passing parameters without
using keyword arguments. This change is necessary even
if you're using RSpec:

Before:

expect { post :create, params }.to change(Project, :count).by(1)

After:

expect { post :create, params: params }.to change(Project, :count).by(1)

6. Next steps
If you successfully followed all of these steps, you
should now be running Rails 5.1! In the next chapter we
will show you how to upgrade from Rails 5.1 to Rails
5.2.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 11: From Rails 5.1

to 5.2
In this chapter we will cover the most important
aspects that you need to know to get your Ruby on Rails
application from Rails 5.1 to 5.2.

1. Ruby version
2. Gems
3. Config files
4. Application code
i. Active Storage
ii. Credentials
iii. ActiveRecord::Dirty
5. Next steps

1. Ruby version
Like Rails 5.0 and 5.1, Rails 5.2 requires at least
Ruby 2.2.2.

2. Gems
At the time of writing, the Rails 5.2 release is
relatively recent, which means that some gems may still
not be fully compatible, or contain deprecation
warnings if you're not using their latest version.
RailsBump can help you check if the gem is compatible

4th Edition
Chapter 1: Getting Started FastRuby.io

with Rails 5.0, but it may have annoying

bugs/deprecation warnings on 5.2. Some (popular) gem
examples are:

friendly_id supports Rails 5.2 without deprecation

warnings on the latest release, 5.2.4. [PR]
activeadmin supports Rails 5.2 without deprecation
warnings on the latest release, 1.3.0. [PR]
acts-as-taggable-on added deprecation-free Rails 5.2
without warnings on the latest release, 6.0.0. [PR]
awesome_nested_set supports Rails 5.2 without
deprecation warnings on the latest release, 3.1.4.
[PR]
jbuilder supports Rails 5.2 with deprecation
warnings on the latest release, 2.7.0. [PR] (not yet
in a release)

3. Config files
Rails includes the rails app:update task. You can use
this task as a guideline as explained thoroughly in
this post.

As an alternative, check out RailsDiff, which provides

an overview of the changes in a basic Rails app between
5.1.x and 5.2.x (or any other source/target versions).

4. Application code
There were not too many deprecations between 5.1 and
5.2 compared to past releases (see the full changelog
here).

4th Edition
Chapter 1: Getting Started FastRuby.io

However, one major feature is the introduction of

ActiveStorage.

a. Active Storage
Active Storage is a replacement for Paperclip and other
gems, like Shrine. Paperclip in particular has been
deprecated. If you're using Paperclip, the maintainers
wrote an in-depth migration guide which you can follow
here.

b. Credentials
Another major feature is the introduction of
Credentials. It will eventually replace the current
config/secrets.yml . Since there are also encrypted secrets
( config/secrets.yml.enc ), its intention is to clear up the
confusion.

Your private credentials will reside in

config/credentials.yml.enc , a file that can be safely
committed into your repository (its contents are
encrypted). To un-encrypt them, there's a master key
( config/master.key ) which should NOT be in your repository
(it's git-ignored by default if you start a new Rails
5.2 app). To edit the credentials, you don't directly
access credentials.yml.enc , instead, there's a bin/rails

credentials:edit task which opens an unencrypted version

of the file (as long as you have the master key).

One controversial aspect of it is the cross-environment

credential sharing, the credentials file will keep all
of your development, test and production keys. For more

4th Edition
Chapter 1: Getting Started FastRuby.io

information on Credentials and a work-around to this

last issue, check out this post, where they use
Hash#dig to configure per-environment credentials.

c. ActiveRecord::Dirty 5.2 API Changes

ActiveRecord::Dirty has some notable changes in this
release.

At this point, you must be running Rails 5.1, so you

may have already seen some of the deprecation warnings
related to the API changes contained in it. Most of
them are behavior changes, and there are some new
additions as well.

To better understand these modifications, we'll take a

look at sample projects in Rails 5.1 and Rails 5.2.

Previous behavior
Notice the deprecation warnings we get when calling
email_changed? , changed? , changes and previous_changes in
Rails 5.1 from within an after_save callback:

4th Edition
Chapter 1: Getting Started FastRuby.io

2.4.2 :010 > user.email = "[email protected]"

=> "[email protected]"
2.4.2 :011 > user.save

From: /Users/mauro-oto/Projects/rails51test/app/models/user.rb @ line 2

1: class User < ApplicationRecord

=> 2: after_save { binding.pry }
3: end

[1] pry(#<User>)> email_changed?

DEPRECATION WARNING: The behavior of `attribute_changed?` inside of afte
=> true
[2] pry(#<User>)> changed?
DEPRECATION WARNING: The behavior of `changed?` inside of after callback
DEPRECATION WARNING: The behavior of `changed_attributes` inside of afte
=> true
[3] pry(#<User>)> changes
DEPRECATION WARNING: The behavior of `changed_attributes` inside of afte
DEPRECATION WARNING: The behavior of `changes` inside of after callbacks
DEPRECATION WARNING: The behavior of `changed` inside of after callbacks
DEPRECATION WARNING: The behavior of `attribute_change` inside of after
DEPRECATION WARNING: The behavior of `attribute_changed?` inside of afte
DEPRECATION WARNING: The behavior of `attribute_change` inside of after
DEPRECATION WARNING: The behavior of `attribute_changed?` inside of afte
=> {"email"=>["[email protected]", "[email protected]"]}
[4] pry(#<User>)> previous_changes
DEPRECATION WARNING: The behavior of `previous_changes` inside of after
deprecated without replacement. In the next release of Rails,
this method inside of `after_save` will return the changes that
were just saved.
=> {}
[5] pry(#<User>)> saved_change_to_email?
=> true
[6] pry(#<User>)> saved_change_to_email
=> ["[email protected]", "[email protected]"]
[7] pry(#<User>)> email_before_last_save
=> "[email protected]"

4th Edition
Chapter 1: Getting Started FastRuby.io

The last three methods' behavior remains unchanged

between Rails 5.1 and Rails 5.2, but the first four
emit those warning messages, and their behavior changes
between these two versions. These changes are best
explained in this commit, and the best aspect of it in
my opinion is explicitness.

It reduces the ambiguity of simply using changed? ,

which would return true when the object was dirty, not
yet saved to the database (within before_save ), and true

after the object was saved to the database (within

after_save ).

The second case will no longer be true , but rather

false . To reduce ambiguity now, you can use the more
explicit saved_changes? method to ask whether the object
has been changed and if its changes were saved to the
database.

New behavior
A developer's intentions will become more clear with
the behavior changes introduced in Rails 5.2:

4th Edition
Chapter 1: Getting Started FastRuby.io

2.4.2 :003 > user.email = "[email protected]"

=> "[email protected]"
2.4.2 :004 > user.save

From: /Users/mauro-oto/Projects/rails52test/app/models/user.rb @ line 2

1: class User < ApplicationRecord

=> 2: after_save { binding.pry }
3: end

[1] pry(#<User>)> email_changed?

=> false
[2] pry(#<User>)> changed?
=> false
[3] pry(#<User>)> changes
=> {}
[4] pry(#<User>)> previous_changes
=> {"email"=>["[email protected]", "[email protected]"]}
[5] pry(#<User>)> saved_change_to_email?
=> true
[6] pry(#<User>)> saved_change_to_email
=> ["[email protected]", "[email protected]"]
[7] pry(#<User>)> email_before_last_save
=> "[email protected]"

attribute_changed? and changed? remain the same when

called within a before_save callback. However, the Rails
core team has also introduced a set of methods which
can help further reduce the potential ambiguity of
changed? before saving to the database:
will_save_change_to_attribute? and has_changes_to_save? :

4th Edition
Chapter 1: Getting Started FastRuby.io

2.4.2 :016 > user.email = "[email protected]"

=> "[email protected]"
2.4.2 :017 > user.has_changes_to_save?
=> true
2.4.2 :018 > user.will_save_change_to_email?
=> true
2.4.2 :019 > user.save
=> true
2.4.2 :020 > user.will_save_change_to_email?
=> nil
2.4.2 :021 > user.has_changes_to_save?
=> false

In conclusion, if you use these methods and are

planning to migrate to Rails 5.2 or even 5.1, you
should take these changes into account.

Must do:
After modifying an object and after saving to the
database, or within after_save :

attribute_changed? should now be saved_change_to_attribute?

changed? should now be saved_changes?

changes should now be saved_changes

previous_changes has no replacement, since the

behavior for it changes.

Optional (less ambiguity, more

readable, but longer):
After modifying an object and before saving to the
database, or within before_save :

attribute_changed? should now be

will_save_change_to_attribute?

4th Edition
Chapter 1: Getting Started FastRuby.io

changed? should now be has_changes_to_save?

changes should now be changes_to_save

5. Next steps
If you successfully followed all of these steps, you
should now be running Rails 5.2! In the next chapter we
will take you from Rails 5.2 to Rails 6.0.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 12: From Rails 5.2

to 6.0
In this chapter we will cover the most important
aspects that you need to know to get your Ruby on Rails
application from version 5.2 to 6.0.

1. Considerations
2. Ruby version
3. Gems
4. Config files
5. Removals
Railties
Action Pack
Action View
Active Record
6. Webpacker
7. Credentials
8. Next steps

1. Considerations
Before beginning with the upgrade process, we recommend
that each version of your Rails app has the latest
patch version before moving to the next major/minor
version. For example, in order to follow this article,
your Rails version should be at 5.2.3 before upgrading
to Rails 6.0.x

2. Ruby version

4th Edition
Chapter 1: Getting Started FastRuby.io

Rails 6.0 requires Ruby 2.5 or later. Check out this

table to see all the required Ruby versions across all
Rails versions.

3. Gems
Make sure you check the Github page of the gems you use
for the project to find out its compatibility with
Rails 6.0. In case you own the gem, you'll need to make
sure it supports Rails 6.0 and if it doesn't, update
it.

4. Config files
Rails includes the rails app:update task. You can use
this task as a guideline as explained thoroughly in
this post.

As an alternative, check out RailsDiff, which provides

an overview of the changes in a basic Rails app between
5.2.x and 6.0.x (or any other source/target versions).

5. Removals
Railties

Remove deprecated after_bundle helper inside plugins

templates.

Remove deprecated support to config.ru that uses the

application class as argument of run .

Remove deprecated environment argument from the rails

commands.

4th Edition
Chapter 1: Getting Started FastRuby.io

Remove deprecated capify! method in generators and

templates.

Remove deprecated config.secret_token .

Action Pack

Remove deprecated fragment_cache_key helper in favor of

combined_fragment_cache_key .

Remove deprecated methods in ActionDispatch::TestResponse:

#success? in favor of #successful? , #missing? in favor

of #not_found? , #error? in favor of #server_error ?

Action View

Remove deprecated image_alt helper.

Remove an empty RecordTagHelper module from which the

functionality was already moved to the
record_tag_helper gem.

Active Record

Remove deprecated #set_stat from the transaction

object.

Remove deprecated #supports_statement_cache? from the

database adapters.

Remove deprecated #insert_fixtures from the database

adapters.

Remove deprecated
ActiveRecord::ConnectionAdapters::SQLite3Adapter#valid_alter_table_t
ype? .

4th Edition
Chapter 1: Getting Started FastRuby.io

Remove support for passing the column name to sum

when a block is passed.

Remove support for passing the column name to count

when a block is passed.

Remove support for delegation of missing methods in

a relation to arel.

Remove support for delegating missing methods in a

relation to private methods of the class.

Remove support for specifying a timestamp name for

#cache_key.

Remove deprecated ActiveRecord::Migrator.migrations_path= .

Remove deprecated expand_hash_conditions_for_aggregates .

6. Webpacker
Webpacker is now the default JavaScript compiler for
Rails 6. You can still manage your JavaScript using the
Asset Pipeline but it might be a good idea to start
migrating to Webpack.

There is a really good screencast that explains

everything about it: How to Use Javascript via
Webpacker in Rails 6

7. Credentials
Rails 6 adds support for multi environment credentials.
That means that now you can run rails credentials:edit --

environment staging and it will create a

config/credentials/staging.yml.enc file where you can store

4th Edition
Chapter 1: Getting Started FastRuby.io

your encrypted credentials for staging (or whatever

environment you want). Rails will know which credential
file should use based on the format of the file. Also,
if you create an environment credential file, it will
take precedence over the default config/credentials.yml.enc .

8. Next steps
If you successfully followed all of these steps, you
should now be running Rails 6.0! In the next chapter we
will take you from Rails 6.0 to Rails 6.1.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 13: From Rails 6.0

to 6.1
In this chapter we will cover the most important
aspects that you need to know to get your Ruby on Rails
application from version 6.0 to 6.1.

1. Preparations
2. Ruby version
3. Gems
4. Config files
5. Rails Guides
6. Removals
Railties
Action Pack
Action View
Action Mailer
Active Record
Active Storage
Active Support
7. Next steps

1. Preparations
Before beginning with the upgrade process, we have some
recommended preparations:

Your Rails app should have the latest patch version

before you move to the next major/minor version.
You should have at least 80% test coverage unless
you have a dedicated QA team.

4th Edition
Chapter 1: Getting Started FastRuby.io

Follow a Git flow workflow to actively manage at

least two environments: staging and production.
Check your Gemfile.lock for incompatibilities by
using RailsBump.
Create a dual boot mechanism, the fastest way to do
this is installing the handy gem next_rails. Find
out more about how and why to dual boot.
To learn more about dual booting with non-backwards
compatible changes you can visit this article.

For full details check out our article on How to

Prepare Your App for a Rails Upgrade.

2. Ruby version
Rails 6.1 requires Ruby 2.5 or later. Check out this
table to see all the required Ruby versions across all
Rails versions.

3. Gems
Make sure you check the GitHub page of the gems you use
for the project to find out its compatibility with
Rails 6.1. In case you are the maintainer of the gem,
you'll need to make sure it supports Rails 6.1 and if
it doesn't, update it. A great site to checkout
compatibility is RailsBump.

4. Config files
Rails includes the rails app:update task. You can use
this task as a guideline as explained thoroughly in
this post.

4th Edition
Chapter 1: Getting Started FastRuby.io

As an alternative, check out RailsDiff, which provides

an overview of the changes in a basic Rails app between
6.0.x and 6.1.x (or any other source/target versions).

5. Rails Guides
It is important to check through the official Rails
Guides and follow any of the steps necessary for your
application.

6. Removals
If you have ignored deprecation warnings on past
version jumps, and haven’t been staying up to date with
them you may find that you have issues with broken
tests or broken parts of the application. If you have
trouble figuring out why something is broken it may be
because a deprecation is removed, so you can check
through this list to see if this may be the case.

Railties

Remove deprecated rake notes tasks.

Remove deprecated connection option in the rails

dbconsole command.

Remove deprecated SOURCE_ANNOTATION_DIRECTORIES

environment variable support from rails notes .

Remove deprecated server argument from the rails

server command.

Remove deprecated support for using the HOST

environment variable to specify the server IP.

4th Edition
Chapter 1: Getting Started FastRuby.io

Remove deprecated rake dev:cache tasks.

Remove deprecated rake routes tasks.

Remove deprecated rake initializers tasks.

Action Pack

Remove deprecated ActionDispatch::Http::ParameterFilter .

Remove deprecated force_ssl at the controller level.

Action View

Remove deprecated escape_whitelist from

ActionView::Template::Handlers::ERB .

Remove deprecated find_all_anywhere from

ActionView::Resolver .

Remove deprecated formats from ActionView::Template::HTML .

Remove deprecated formats from

ActionView::Template::RawFile .

Remove deprecated formats from

ActionView::Template::Text .

Remove deprecated find_file from ActionView::PathSet .

Remove deprecated rendered_format from

ActionView::LookupContext .

Remove deprecated find_file from ActionView::ViewPaths .

Remove deprecated format argument

ActionView::Base#initialize .

Remove deprecated ActionView::Template#refresh .

4th Edition
Chapter 1: Getting Started FastRuby.io

Remove deprecated ActionView::Template#original_encoding .

Remove deprecated ActionView::Template#variants .

Remove deprecated ActionView::Template#formats .

Remove deprecated ActionView::Template#virtual_path= .

Remove deprecated ActionView::Template#updated_at .

Make locals argument required on

ActionView::Template#initialize .

Remove deprecated
ActionView::Template.finalize_compiled_template_methods and
config.action_view.finalize_compiled_template_methods .

Remove deprecated support to calling

ActionView::ViewPaths#with_fallback with a block.

Remove deprecated support to passing absolute paths

to render template: .

Remove deprecated support to passing relative paths

to render file: .

Remove deprecated support to template handlers that

don't accept two arguments.

Remove pattern argument in

ActionView::Template::PathResolver .

Remove support to call private methods from object

in some view helpers.

Action Mailer

Remove deprecated ActionMailer::Base.receive in favor of

Action Mailbox.

4th Edition
Chapter 1: Getting Started FastRuby.io

Active Record

Remove deprecated methods from

ActiveRecord::ConnectionAdapters::DatabaseLimits .
column_name_length table_name_length columns_per_table

indexes_per_table columns_per_multicolumn_index sql_query_length

joins_per_query

Remove deprecated
ActiveRecord::ConnectionAdapters::AbstractAdapter#supports_multi_ins
ert? .

Remove deprecated
ActiveRecord::ConnectionAdapters::AbstractAdapter#supports_foreign_k
eys_in_create? .

Remove deprecated
ActiveRecord::ConnectionAdapters::PostgreSQLAdapter#supports_ranges?
.

Remove deprecated ActiveRecord::Base#update_attributes and

ActiveRecord::Base#update_attributes! .

Remove deprecated migrations_path argument in

ActiveRecord::ConnectionAdapter::SchemaStatements .

Remove deprecated
config.active_record.sqlite3.represent_boolean_as_integer .

Remove deprecated methods from

ActiveRecord::DatabaseConfigurations .

Remove deprecated ActiveRecord::Result#to_hash method.

Remove deprecated support for using unsafe raw SQL

in ActiveRecord::Relation methods.

Active Storage

4th Edition
Chapter 1: Getting Started FastRuby.io

Remove deprecated support to pass :combine_options

operations to ActiveStorage::Transformers::ImageProcessing .
Remove deprecated
ActiveStorage::Transformers::MiniMagickTransformer .
Remove deprecated config.active_storage.queue .
Remove deprecated ActiveStorage::Downloading .

Active Support

Remove deprecated fallback to I18n.default_local when

config.i18n.fallbacks is empty.

Remove deprecated LoggerSilence constant.

Remove deprecated
ActiveSupport::LoggerThreadSafeLevel#after_initialize .

Remove deprecated Module#parent_name , Module#parent and

Module#parents .

Remove deprecated file

active_support/core_ext/module/reachable .

Remove deprecated file

active_support/core_ext/numeric/inquiry .

Remove deprecated file

active_support/core_ext/array/prepend_and_append .

Remove deprecated file

active_support/core_ext/hash/compact .

Remove deprecated file

active_support/core_ext/hash/transform_values .

Remove deprecated file

active_support/core_ext/range/include_range .

4th Edition
Chapter 1: Getting Started FastRuby.io

Remove deprecated ActiveSupport::Multibyte::Chars#consumes?

and ActiveSupport::Multibyte::Chars#normalize .

Remove
deprecated ActiveSupport::Multibyte::Unicode.pack_graphemes ,
ActiveSupport::Multibyte::Unicode.unpack_graphemes ,
ActiveSupport::Multibyte::Unicode.normalize ,
ActiveSupport::Multibyte::Unicode.downcase ,
ActiveSupport::Multibyte::Unicode.upcase and
ActiveSupport::Multibyte::Unicode.swapcase .

Remove
deprecated ActiveSupport::Notifications::Instrumenter#end= .

7. Next steps
If you successfully followed all of these steps, you
should now be running Rails 6.1!

Now it's time we go to the Next Steps for some tips so

you never fall behind again.

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 14: Next Steps

If you have gotten this far, that means that you are
running the latest version of Rails in production.
Congratulations! That is a huge achievement and you
should be proud of your team's efforts.

Now is the time to make decisions so that you never

fall behind again. What can you and your team do to
keep up with latest releases?

Continuous Integration and

Dual Boot
If you are using a CI service like Travis CI or Circle
CI, you can configure the project to run both versions
of your test suites. You'll need to push the
Gemfile.lock file to your repository and configure them
like this:

Circle CI
You can add a second job to use the Gemfile.next file:

4th Edition
Chapter 1: Getting Started FastRuby.io

jobs:
"build-rails-5-2":
docker:
# this is your original config ...
- image: circleci/ruby:2.6.0-node-browsers
environment:
- PGHOST=localhost
- PGUSER=ubuntu
- RAILS_ENV=test
- RACK_ENV=test
- COVERAGE=true
- DATABASE_URL=postgres://ubuntu@localhost:5432/piedpiper_test
# ...

"build-rails-6-0":
docker:
# this is the next rails config ...
- image: circleci/ruby:2.6.0-node-browsers
environment:
- PGHOST=localhost
- PGUSER=ubuntu
- RAILS_ENV=test
- RACK_ENV=test
- COVERAGE=true
- DATABASE_URL=postgres://ubuntu@localhost:5432/piedpiper_test
- BUNDLE_GEMFILE=Gemfile.next
# ...
workflows:
version: 2
build:
jobs:
- "build-rails-5-2"
- "build-rails-6-0"

The important sections of the config are the

environment variable BUNDLE_GEMFILE=Gemfile.next and having
2 jobs on the workflows section of the config file.

Travis CI

4th Edition
Chapter 1: Getting Started FastRuby.io

Here is the configuration if you prefer Travis CI:

sudo: false
language: ruby
cache:
bundler: true
directories:
- travis_phantomjs
rvm:
- 2.2.6
gemfile:
- Gemfile
- Gemfile.next
services:
- memcached
- postgresql
addons:
postgresql: "9.4"
before_install:
- gem install bundler -v 1.16.2
before_script:
- bundle install
- psql -c 'create database epets_test;' -U postgres
- RAILS_ENV=test bundle exec rake db:structure:load
script: RAILS_ENV=test bundle exec rake

You need to set a second gemfile in the gemfile:

section.

Keep track of outdated

dependencies
You could add a spec to your suite that keeps track of
outdated dependencies. Bundler has an easy way to show
you all your outdated gems: bundle outdated . You could

4th Edition
Chapter 1: Getting Started FastRuby.io

have it fail every time it detects an outdated gem.

This would keep you and your team focused on upgrading
as soon as possible.

Every version bump could be a pull request which would

run the test suite and follow the standard quality
assurance process: Pull request, code review, staging
deployment, QA, production deployment.

Keep up with Rails' master

Once you have your app running the latest Rails
version, you can set up dual boot to point to Rails'
master branch. That way you can prepare your code in
advance for the next version.

These tips will help you next time you need to upgrade
the minor/major version of Rails!

4th Edition
Chapter 1: Getting Started FastRuby.io

Chapter 15: Need Help?

We hope that this guide has helped you get to grips
with what your upgrade requires.

But, if you are short on dev time or would like an

experienced partner then we are happy to help.

Visit FastRuby.io to read all about us, or check out

The Roadmap if you would like us to audit your code and
assess what is needed for your upgrade.

4th Edition