How to Point an Agent at a Ruby 3.4 and Rails 8.1 Upgrade

An agent does not need a tour of Rails 8.1 to upgrade an app. It needs the upgrade guide, one version move, and the test suite. The page to put in the prompt is the Rails 8.1 upgrading guide. New Active Record APIs are a later pass. They are not the upgrade.

The guide opens with a check that is easy to skip: have a reason, and have tests. If the suite does not exercise the bulk of the app, an agent cannot tell a real break from a green run. Say that in the prompt. If coverage is thin, the first job is tests, and the version bump waits.

Ruby first, Rails second

The guide's Ruby rule is short. Rails 8.0 and Rails 8.1 require Ruby 3.2.0 or newer. Upgrade Ruby and Rails separately. Upgrade to the latest Ruby you can first, then upgrade Rails.

For an app still on 3.3, that first prompt is Ruby 3.4 and nothing else. Do not change the Rails version in the same diff. Boot the app, run the suite, and stop. A syntax error on 3.4 is a Ruby problem. It is not a license to start the Rails bump.

One minor version, then the next

Rails version numbers are Major.Minor.Patch. Major and minor versions may change the public API. Patch versions are bug fixes. The guide says to move one minor version at a time so the deprecation warnings are usable. The sequence is:

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 until you reach the target. An app on 7.2 does not jump to 8.1. It goes to the latest 7.2 patch, then the latest 8.0 patch, then 8.1. A prompt that says "set the Gemfile to Rails 8.1" throws away the warnings the guide is written around.

Each move is the same four steps from the guide:

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

That is the whole prompt. The agent does not also rename pool settings, deprecate associations, or restyle blocks.

app:update is a review, not a yes

After the Gemfile change, the guide says to run bin/rails app:update. It creates new files and offers changes to old ones 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
...

Tell the agent to stop on every conflict and show the file. Overwriting config/application.rb because the prompt said "Y" is how an upgrade loses your own configuration. Review the diff afterward. The guide says the diff and merge tools can be set with THOR_DIFF and THOR_MERGE.

Leave load_defaults where it is

After those steps the app still runs on the previous framework defaults. config.load_defaults in config/application.rb has not changed. The update task adds config/initializers/new_framework_defaults_X_Y.rb, with the target Rails version in the name. For this bump that is new_framework_defaults_8_1.rb.

Uncomment those settings one at a time, across deploys, with the suite between them. When the app is ready for the new defaults, remove the initializer and flip config.load_defaults. Doing both in the version-bump commit hides which change broke a request.

The 8.1 change the guide names

The 8.0-to-8.1 section of the guide points at the release notes for the rest of the release, and names one dump change. Active Record sorts columns in schema.rb alphabetically, so the file stops flip-flopping with migration order. structure.sql still preserves exact column order if you need that.

Regenerate the schema and commit that diff by itself. It will touch almost every table. Mixed into a Gemfile bump, it hides a real migration. The agent can run the dump. It should not "fix" the new order back to the old one.

A prompt that can be reviewed looks like this:

Follow the Rails 8.1 upgrading guide. We are on the latest Rails 8.0 patch and Ruby 3.4. Move only to Rails 8.1: change the Gemfile, run bundle update rails, and run the test suite. Do not change config.load_defaults. Do not answer overwrite prompts in bin/rails app:update; stop and show me each conflict. Commit nothing.

The suite decides whether that move holds. A deprecation warning is a result to list, not a feature to adopt in the same patch.

When the path is the thing nobody wants to walk one version at a time, Rails Agency will run it that way: Ruby first, one minor at a time, defaults left alone until the app is ready.