Migrating from Ruby on Rails 5 to 7: A Comprehensive Guide

Migrating from Ruby on Rails version 5 to version 7 involves multiple steps to ensure compatibility with the latest features and improvements. Follow this comprehensive guide to facilitate a smooth migration process.

Overview of the Migration Process

1. Review Release Notes

• Understand Changes: Begin by thoroughly reviewing the release notes for Ruby on Rails versions 6 and 7. These notes provide an overview of new features, improvements, and changes introduced in each version.
• Identify Breaking Changes: Look for any breaking changes or backward-incompatible modifications that could affect your application. By addressing these early, you can proactively minimize issues during the migration.
• Discover Deprecations: Note deprecated APIs, methods, and features that will be removed in future versions. This information helps you update your application code to maintain compatibility with Rails 7.
• Plan Migration Steps: Use release notes as a roadmap for your migration process. Understand the scope of changes to prioritize tasks, allocate resources, and create a plan that minimizes downtime and disruption.
• Stay Informed: Regularly review the latest Rails releases and release notes to stay informed about new features, performance enhancements, and security updates that can benefit your application.

2. Assess Compatibility with Ruby 3 and Rails 7

• Ensure Ruby Compatibility: Ruby on Rails 7 requires Ruby 3.0 or later. Before migrating, verify that your application is compatible with Ruby 3. Review Ruby 3.0 release notes to understand any language changes or features that may impact your application.
• Check Gem Compatibility: Examine the compatibility of your application’s gems and dependencies with Rails 7 and Ruby 3.0. Check the documentation and the repository of each gem for information on supported versions of Rails and Ruby. Update gems that are not compatible or have been deprecated.

3. Test Environment Setup and Code Review

• Test Environment Setup: Create an isolated test environment using tools like Docker or virtual machines to simulate the migration process. This allows you to safely test compatibility with Rails 7 without impacting your production environment.
• Run Automated Tests: Execute your application’s automated test suite against Rails 7. Look for compatibility issues or regressions, and update tests as needed to pass with Rails 7. Focus on controller tests, model tests, and integration tests, which may be affected by changes in Rails behavior or APIs.
• Manual Code Review: Conduct a thorough manualreview of your codebase to identify potential compatibility issues with Rails 7. Look for deprecated APIs, syntax changes, or usage patterns that need updates. Consider using static analysis tools or code linters to automate this process and identify potential issues more efficiently.
• Verify Third-Party Integrations: If your application integrates with third-party services or APIs, ensure these integrations are compatible with Rails 7. Check the documentation and release notes of each integration for any updates or changes required for compatibility with Rails 7 and Ruby 3.0.

4. Upgrade Ruby Version

• Upgrade to Ruby 3.x: If your application isn’t running on Ruby 3 yet, upgrade it to Ruby 3.x to benefit from performance improvements and new language features. Thoroughly test your application post-upgrade to ensure it functions as expected.
• Understand New Features: Familiarize yourself with the new features and enhancements introduced in the version of Ruby you’re upgrading to. Review Ruby 3.0 release notes documentation to understand language changes, performance upgrades, and security enhancements.
• Check Application Compatibility: Assess your application’s compatibility with the target version of Ruby. Review compatibility guides and migration notes from the Ruby core team for potential issues or breaking changes affecting your application. Look out for changes in syntax, semantics, and behavior that may require updates to your codebase.
• Update Dependencies: Verify that all dependencies, including gems and libraries, are compatible with the target version of Ruby. Check documentation and GitHub repositories of each dependency for information on supported Ruby versions and necessary updates.
• Choose Upgrade Method: Select an upgrade method suitable for your environment. Use package managers like Ruby Version Manager (RVM) or rbenv to install and manage multiple Ruby versions, or consider using Docker containers or virtual machines to isolate your application and test the upgrade.
• Follow the Upgrade Process: Follow the recommended upgrade steps, including installing the new version of Ruby, updating environment variables and configuration settings, and confirming that the upgrade was successful.
• Verify Functionality: After upgrading, test your application to confirm that all functionality remains intact and that your application behaves as expected. Run your test suite, including unit, integration, and system tests, to ensure all features work correctly with the new Ruby version.

5. Update Gemfile and Resolve Deprecations

• Update Gemfile: Specify Rails version 7.x in your Gemfile. Also, update any other gems to their latest compatible versions. Check for any deprecated or replaced gems and use alternatives when necessary.
• Resolve Deprecations: Pay attention to deprecation warnings or errors during the upgrade. Rails issues these warnings to help you identify outdated code and migrate to newer APIs or patterns. Take the time to refactor your codebase to remove deprecated features to ensure compatibility and future-proof your application.

6. Adjust Configuration

• Review Configuration Files: Update files such as config/application.rb and config/environments/*.rb for Rails 7.
• Accommodate Changes: Adjust to new defaults and conventions in Rails 7 configurations.  and make any necessary adjustments to accommodate changes in Rails 7 configuration defaults or conventions.

7. Update Routes

• Review Routes: Examine your application’s routes (config/routes.rb) for compatibility with Rails 7.
• Update Syntax: Modify any syntax or usage patterns that have changed in Rails 7.

8. Review Database Migrations

• Check Compatibility: Ensure your database migrations are compatible with Rails 7.
• Adjust Migrations: Modify migration files as needed to adhere to Rails 7 conventions and best practices.
• Test Thoroughly: Test your migrations to ensure correct functionality and data consistency.

9. Run Tests

• Test Suite: Thoroughly run your test suite to ensure all tests pass after upgrading. Look for test cases or fixtures that rely on deprecated behavior or APIs, and update them as needed
• Add Tests for New Features: Consider adding tests to cover new features or functionality introduced in Rails 7. This will help ensure your application takes full advantage of Rail 7’s enhancements and improvements while maintaining stability and compatibility.

10. Performance Optimization

• Take Advantage of Improvements: Utilize performance improvements in Rails 7.
• Review Metrics: Analyze performance metrics to identify areas for further optimization.

11. Deployment

• Deploy to Staging: Deploy your upgraded application to a staging environment.
• Final Testing: Conduct comprehensive integration testing in a production-like environment.

12. Monitor and Iterate

• Monitor Production: Observe your application in production after the upgrade. Monitor performance, error rates, and other key metrics closely.
• Address Issues Promptly: Respond quickly to any issues or regressions that arise. Resolving these problems promptly will help maintain stability and user satisfaction.
• Iterate and Improve: Continuously iterate on your application to enhance performance, stability, and user experience. Use the insights gained from monitoring to guide your optimization efforts.

Major Breaking Changes in Rails 7

Ruby on Rails 7 introduces several breaking changes across various components. Understanding these changes is crucial for a successful migration.

Railties

• Removed deprecated config in dbconsole

Action Pack

• Removed deprecated methods and configurations:

ActionDispatch::Response.return_only_media_type_on_content_ty

Rails.config.action_dispatch.hosts_response_app

ActionDispatch::SystemTestCase#host!

• Passing a path to fixture_file_upload relative to fixture_path is no longer supported

Action View

• Remove deprecated configuration

Rails.config.action_view.raise_on_missing_translations

• button_to infers HTTP verb [method] from an Active Record object used to build URLs:

button_to("Do a POST", [:do_post_action, Workshop.find(1)])
# Before
#=> <input type="hidden" name="_method" value="post" autocomplete="off" />
# After
#=> <input type="hidden" name="_method" value="patch" autocomplete="off" />

Action Mailer

• Removed deprecated ActionMailer::DeliveryJob and ActionMailer::Parameterized::DeliveryJob in favor of ActionMailer::MailDeliveryJob

Active Record

Database Configuration

• Removed deprecated database keyword argument from connected_to
• Removed deprecated ActiveRecord::Base.allow_unsafe_raw_sql
• Removed deprecated option :spec_name in the configs_for method

PostgreSQL Database

• Removed deprecation warning when :interval column is used in PostgreSQL database

Connection and Type Casting

• Removed deprecated support to resolve connection using primary as connection specification name
• Removed deprecated support to quote ActiveRecord::Base objects
• Remove deprecated support to type cast to database values ActiveRecord::Base objects

Methods and Rake Tasks

• Removed deprecated support to pass a column to type_cast
• Removed deprecated DatabaseConfig#config method
• Removed deprecated rake tasks:

db:schema:load_if_ruby

db:structure:dump

db:structure:load

db:structure:load_if_sql

db:structure:dump:#{name}

db:structure:load:#{name}

db:test:load_structure

db:test:load_structure:#{name}

Search and Tasks

• Removed deprecated support to Model.reorder(nil).first to search using non-deterministic order
• Removed deprecated environment and name arguments from
  Tasks::DatabaseTasks.schema_up_to_date?
• Removed deprecated methods and properties including:

Tasks::DatabaseTasks.dump_filename

Tasks::DatabaseTasks.schema_file

Tasks::DatabaseTasks.spec

Tasks::DatabaseTasks.current_config

ActiveRecord::Connection#allowed_index_name_length

ActiveRecord::Connection#in_clause_length

ActiveRecord::DatabaseConfigurations::DatabaseConfig#spec_name

ActiveRecord::Base.connection_config

ActiveRecord::Base.arel_attribute

ActiveRecord::Base.configurations.default_hash

ActiveRecord::Base.configurations.to_h

ActiveRecord::Result#map! and ActiveRecord::Result#collect!

ActiveRecord::Base#remove_connection

Tasks

• Deprecated Tasks::DatabaseTasks.schema_file_type

Active Model

• Removed deprecated enumeration of ActiveModel::Errors instances as a Hash
• Removed deprecated methods from  ActiveModel::Errors including:

ActiveModel::Errors#to_h

ActiveModel::Errors#slice!

ActiveModel::Errors#values

ActiveModel::Errors#keys

ActiveModel::Errors#to_xml

• Removed deprecated support concat errors to ActiveModel::Errors#messages
• Removed deprecated support to clear errors from ActiveModel::Errors#messages
• Removed deprecated support to delete errors from ActiveModel::Errors#messages
• Removed deprecated support to use []= in ActiveModel::Errors#messages
• Removed support to Marshal and YAML load Rails 5.x error format
• Removed support to Marshal load Rails 5.x ActiveModel::AttributeSet format

Active Support

• Removed deprecated config.active_support.use_sha1_digests
• Removed deprecated URI.parser
• Removed deprecated support to use Range#include? to check the inclusion of a value in a date time range is deprecated
• Removed deprecated

ActiveSupport::Multibyte::Unicode.default_normalization_form

• Deprecated passing a format to #to_s in favor of #to_fs in Array, Range, Date, DateTime, Time, BigDecimal, Float and, Integer

Active Job

• Removed deprecated behavior that was not halting after_enqueue/after_perform callbacks when a previous callback was halted with throw :abort
• Removed deprecated :return_false_on_aborted_enqueue option
• Deprecated Rails.config.active_job.skip_after_callbacks_if_terminated

Action Mailbox

• Removed deprecated

Rails.application.credentials.action_mailbox.mailgun_api_key

Removed deprecated environment variable MAILGUN_INGRESS_API_KEY

Final Thoughts

Successfully upgrading your Ruby on Rails application from version 5 to 7 requires careful planning and diligent execution. Follow this guide to make a smooth transition and leverage the latest features and improvements on Rails 7.

Ensure thorough testing and updating at each stage to maintain stability and compatibility. By staying informed and iterating on your application, you can prepare it for future developments in the Rails ecosystem.
Start planning your migration today to modernize your application and set it up for long-term success. Feel free to connect with P2H for additional support and guidance on best practices.