Rails Update.md

Workflow advice

When upgrading Rails versions(major or minor), we can encounter lots of unique issues.
I am writing some generic advice on how you want to tackle the update in principle.

Do a separate step for each major rails versions. For instance, Rails 3 to 5, there can be two steps: 3.x -> 4.2 -> 5.2
Do not bundle update, which can cause serious problems. Please, only update gems which have dependency errors of rails.

When we update patch(0.0.x)level, it is enough just only to update rails gem.
However, major(x.0.0) or minor(0.x.0) version need to update, we need to follow below workflow

Workflow

Update rails gem in Gemfile - gem "rails", "~> 5.2.3"
Run bundle update rails
If there are dependency errors, only update the gems which have dependency errors- update Gemfile and Run bundle update gem_name.
Run rails console and fix out errors while starting up.
Run rails server and fix out errors while starting up.
Run rails db:migrate
Run rails app:update and edit configuration files - Do not overwrite configuration files
Do step 4 and 5 again
Run unit and integration test(Rspec, Cucumber and etc.) and fix out all errors.
Run rails server and check each pages.
Fix all deprecation warnings.
Backup staging database and deploy to staging server
Check by clicking around staging server.
Backup production database and deploy to production server
Check by clicking around production server.

Configuration

After running rails app:update, there are several configuration files which are generated.
One of those files is config/initializers/new_framework_defaults.rb which allow you to upgrade to new defaults one by one.

For instance, If you update rails from 4 to 5.2 through 2 steps(4->5, 5->5.2), there are new_framework_defaults.rb and new_framework_defaults_5_2.rb by running rails app:update in each rails version.

If config.load_defaults 5.2 like below, you do not need new_framework_defaults.rb and new_framework_defaults_5_2.rb

# config/application.rb
...
module xxxxx
  class Application < Rails::Application
   config.load_defaults 5.2
  ...
  end
end

However, if config.load_defaults 5.0, you need new_framework_defaults_5_2.rb.
If there is no config.load_defaults, you need both new_framework_defaults.rb and new_framework_defaults_5_2.rb

Ruby version

Rails 6 requires Ruby 2.5.0 or newer.
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.

Referece

Here is official document for upgrading

Configuration documents

Release_notes

JamesYang76/Rails Update.md

Workflow advice

Workflow

Configuration

Ruby version

Referece