Skip to main content

Ruby Upgrade Guide

This guide documents the process for upgrading Ruby versions in the Reports application.

Current Version: Ruby 3.3.13​

The application currently uses Ruby 3.3.13, which is the latest stable release in the 3.3.x series.

Upgrading to Ruby 3.4.x​

Ruby 3.4.x introduces several new features and potential breaking changes. This section documents the upgrade path and considerations.

Key Changes in Ruby 3.4.x​

Based on Ruby 3.4 release notes and preview versions, here are the main changes to be aware of:

  1. Performance Improvements

    • YJIT improvements for better runtime performance
    • Memory allocation optimizations

  2. New Features

    • Enhanced pattern matching capabilities
    • New standard library additions
    • Improved debugging tools

  3. Deprecations and Breaking Changes

    • Review Ruby 3.4 NEWS file for specific deprecations
    • Some standard library gems may be moved to bundled gems
    • Potential changes to keyword argument handling

Preparation Steps for Ruby 3.4.x​

Before upgrading to Ruby 3.4.x, complete these preparation steps:

1. Address Current Deprecation Warnings​

Run the test suite and application with deprecation warnings enabled:

RUBYOPT="-W:deprecated" bundle exec rspec

Fix any deprecation warnings that appear, as deprecated features may be removed in Ruby 3.4.x.

2. Update Dependencies​

Ensure all gems are compatible with Ruby 3.4.x:

# Check for outdated gems
bundle outdated

# Update gems (carefully)
bundle update

Pay special attention to:

  • Rails and related gems
  • Database adapters (pg gem)
  • Background job processors (sidekiq)
  • Testing frameworks (rspec, capybara)

3. Review Standard Library Changes​

Ruby 3.4 may move some standard library features to bundled gems. Review your Gemfile to ensure you explicitly include any standard library features you use:

  • csv - Already included in Gemfile ✓
  • bigdecimal - Already included in Gemfile ✓
  • mutex_m - Already included in Gemfile ✓
  • drb - Already included in Gemfile ✓

4. Test in a Staging Environment​

Before upgrading production:

  1. Update .ruby-version to ruby-3.4.0 (or latest 3.4.x)
  2. Update Gemfile ruby constraint to ruby '~> 3.4.0'
  3. Update workflow files if needed
  4. Run full test suite
  5. Perform manual testing of critical features
  6. Monitor for performance regressions

Upgrade Process​

When Ruby 3.4.0 is released and you're ready to upgrade:

1. Update Version Files​

# .ruby-version
ruby-3.4.0

# Gemfile
ruby '~> 3.4.0'

2. Update CI/CD Configuration​

The GitHub Actions workflows use ruby/setup-ruby@v1 which automatically reads from .ruby-version, so no changes should be needed in:

  • .github/workflows/testing.yml
  • .github/workflows/rubocop.yml
  • .github/workflows/deploy.yml

3. Update Docker Configuration​

Update docker-compose.yml:

args:
  RUBY_VERSION: '3.4.0'

4. Update Documentation​

Update the following files:

  • .github/copilot-instructions.md - Update Ruby version in setup instructions
  • This file (ruby-upgrade-guide.md) - Update current version section

5. Install and Test​

# Install Ruby 3.4.0 (using your version manager)
rbenv install 3.4.0
# or
rvm install 3.4.0

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Run linters
bundle exec rubocop

6. Address Any Issues​

  • Fix test failures
  • Update code for compatibility
  • Address performance regressions
  • Fix deprecation warnings

Known Potential Issues​

Rails 7.0 Compatibility​

Rails 7.0 is compatible with Ruby 3.3, but compatibility with Ruby 3.4 should be verified:

  • Check Rails GitHub issues for Ruby 3.4 compatibility reports
  • Consider upgrading to Rails 7.1 or 7.2 if needed

Gem Compatibility​

Some gems may not immediately support Ruby 3.4:

  • Check gem GitHub repositories for Ruby 3.4 support
  • Look for alternative gems if needed
  • Consider contributing fixes to gems if possible

Psych Gem​

The application currently pins psych to version < 4 for Rails 7.0 compatibility. This constraint should be reviewed when upgrading Rails.

Testing Checklist​

Before deploying Ruby 3.4.x to production:

  • All RSpec tests pass
  • Rubocop runs without errors
  • No deprecation warnings in test output
  • Manual testing of critical features:
    • User authentication and authorization
    • Content management operations
    • Email campaign functionality
    • Payment processing (Stripe integration)
    • Background job processing (Sidekiq)
    • API endpoints (GraphQL and REST)
  • Performance testing shows no regressions
  • Staging environment runs successfully for 24+ hours

Rollback Plan​

If issues arise after upgrading:

  1. Revert version files to previous Ruby version
  2. Run bundle install to restore gem versions
  3. Redeploy previous version
  4. Document issues encountered for future upgrade attempt

Resources​

Upgrade History​

  • 2026-10-23: Upgraded from Ruby 3.3.9 to Ruby 3.3.13
  • 2024-10-20: Upgraded from Ruby 3.3.6 to Ruby 3.3.9
  • Previous: Ruby 3.3.6 (initial 3.3.x version)