More at rubyonrails.org:

Upgrading Ruby on Rails

This guide provides steps to be followed when you upgrade your applications to a newer version of Ruby on Rails. These steps are also available in individual release guides.

1. General Advice

Before attempting to upgrade an existing application, you should be sure you have a good reason to upgrade. You need to balance several factors: the need for new features, the increasing difficulty of finding support for old code, and your available time and skills, to name a few.

1.1. Test Coverage

The best way to be sure that your application still works after upgrading is to have good test coverage before you start the process. If you don't have automated tests that exercise the bulk of your application, you'll need to spend time manually exercising all the parts that have changed. In the case of a Rails upgrade, that will mean every single piece of functionality in the application. Do yourself a favor and make sure your test coverage is good before you start an upgrade.

1.2. Ruby Versions

Rails generally stays close to the latest released Ruby version when it's released:

  • Rails 8.0 and 8.1 require Ruby 3.2.0 or newer.
  • Rails 7.2 requires Ruby 3.1.0 or newer.
  • Rails 7.0 and 7.1 require Ruby 2.7.0 or newer.
  • Rails 6 requires Ruby 2.5.0 or newer.
  • Rails 5 requires Ruby 2.2.2 or newer.

It's a good idea to upgrade Ruby and Rails separately. Upgrade to the latest Ruby you can first, and then upgrade Rails.

1.3. The Upgrade Process

When changing Rails versions, it's best to move slowly, one minor version at a time, in order to make good use of the deprecation warnings. Rails version numbers are in the form Major.Minor.Patch. Major and Minor versions are allowed to make changes to the public API, so this may cause errors in your application. Patch versions only include bug fixes, and don't change any public API.

The process should go as follows:

  1. Write tests and make sure they pass.
  2. Move to the latest patch version after your current version.
  3. Fix tests and deprecated features.
  4. Move to the latest patch version of the next minor version.

Repeat this process until you reach your target Rails version.

1.3.1. Moving between versions

To move between versions:

  1. Change the Rails version number in the Gemfile and run bundle update rails.
  2. Change the versions for Rails JavaScript packages in package.json and run bin/rails javascript:install if running jsbundling-rails.
  3. Run the Update task.
  4. Run your tests.

You can find a list of all released Rails gems here.

1.4. The Update Task

Rails provides the bin/rails app:update command. After updating the Rails version in the Gemfile, run this command. This will help you with the creation of new files and changes of old files in an interactive session.

$ bin/rails app:update
       exist  config
    conflict  config/application.rb
Overwrite /myapp/config/application.rb? (enter "h" for help) [Ynaqdh]
       force  config/application.rb
      create  config/initializers/new_framework_defaults_8_0.rb
...