Rails Update

• Using next_rails... or How to Stay Sane While Upgrading Rails to the Next Major/Minor Version
• Choosing a bundle
• Choosing gems to install
• Choosing code to run
• Choosing CI Jobs to run
• How to get to a usable new Rails version

Using next_rails... or How to Stay Sane While Upgrading Rails to the Next Major/Minor Version

In Rails version upgrades, issues often arise due to removal of deprecated Rails features and similar. Instead of addressing all issues in a single GIANT pull request, using next_rails and conditional CI jobs allow us to do so in multiple small pull requests without affecting the current Rails version.

Choosing a bundle

next_rails allows us to boot our app against two dependency bundles. Our current bundle (Gemfile + Gemfile.lock) and a bundle for the next Ruby on Rails version (Gemfile.next + Gemfile.next.lock). If you prefix any bundler command with next then it's using the bundle for the next Ruby on Rails version. Like...

• next bundle install
• next bundle exec rails c

Choosing gems to install

Inside our Gemfile you can use the next? method to distinguish between bundles. Like Gemfile contains by default this:

if next?
  gem 'rails', '~> 8.0.0'
else
  gem 'rails', '~> 7.2.0'
end

If we are using the bundle for the next Ruby on Rails version we install the rails GEM with the version 8.0.0 (or similar), if we are using our normal bundle it's using the version 7.2.0 (or similar).

This way you can add different gems to one bundle without affecting the other.

Choosing code to run

You may need to branch application code as well:

if NextRails.next?
  # Do things "the Rails 8.0 way"
else
  # Do things "the Rails 7.2 way"
end

Or use NextRails.current? for the inverse check:

if NextRails.current?
  # Do things "the Rails 7.2 way"
else
  # Do things "the Rails 8.0 way"
end

Choosing CI jobs to run

By default our CI does not run jobs with the next Ruby on Rails version.

If your PR comes from a upstream branch that starts with the string next_rails- then our CI will run...

• next_rails-linters: rubocop, haml_lint, database_consistency etc.
• next_rails-rspec: all rspec spec
• next_rails-minitest: all minitest tests

with the bundle for the next Ruby on Rails version.

Those CI jobs are NOT required to be green to get merged.

How to get to a usable new Rails version

Updating the bundle

Usually you start with getting the bundle for the next Rails version updated.

1. Create a branch: git checkout -b next_rails-bundle-update
2. Start the dev-env: docker compose run --rm frontend /bin/bash -l
3. Make sure to choose the right gems to install
4. Install the bundle: next bundle install
5. Commit changes: git add -A; git commit -av -m 'Updated Gemfile.next.lock'
6. Push branch upstream: git push upstream next_rails-bundle-update
7. Create the PR and get it merged

That PR will most likely already show you a bunch of failing next_rails... CI jobs, that's fine as they are not required to be green.

Make next_rails... CI jobs turn green without breaking the usual CI jobs.

Now the fun starts 🥳 You need to follow the Rails Upgrade Guide and get all next_rails... CI jobs green. This usually at least means running next bundle exec rails app:update and deciding what to do with the proposed changes.

For each of the changes you can submit individual PRs

1. Create another branch: git checkout -b next_rails-fix-something-rails-app-update-told-me
2. Fix the CI error using the methods above
3. Push branch upstream: git push upstream next_rails-fix-something-rails-app-update-told-me
4. Create the PR and get it merged

Repeat until all the next_rails... CI jobs turn green while the

Make the new Rails version the default

Once those next_rails... jobs are green you...

1. make the new bundle the default in Gemfile

   if next?
     gem 'rails', '~> 9.0.0'
   else
     gem 'rails', '~> 8.0.0'
     gem 'foo'
     gem 'bar'
   end

2. Drop all old code guarded by NextRails.next?
3. Configure the new framework defaults
4. Create another branch: git checkout -b next_rails-8.0
5. Push branch upstream: git push upstream next_rails-8.0
6. Create the PR and get it merged