// Upgrade Rails framework to a newer version following the smooth upgrade methodology
| name | upgrade-rails |
| description | Upgrade Rails framework to a newer version following the smooth upgrade methodology |
Use this skill when upgrading Rails to a newer minor or patch version.
Based on the Smooth Ruby and Rails Upgrades methodology. Key principles:
For a Rails upgrade from e.g. 7.0.x to 7.2.x:
Never jump multiple minors at once.
cd apps/rails_application
bundle outdated rails
rails -v
Check current version, target version, and plan the minor-version steps.
bundle exec bundler-audit check --update
Address any CVEs in separate preparatory commits. Then attempt the update to see if gems conflict:
bundle update rails --conservative
If gems conflict, update blocking gems first in separate commits on main.
Run the full test suite and grep for deprecation warnings:
make test 2>&1 | grep -i deprecat
Fix each deprecation in its own commit, deployed to main before the version bump. This is the backport-first approach — preparatory work lands independently.
In apps/rails_application/Gemfile, update:
gem "rails", "~> X.Y.0"
Then:
cd apps/rails_application
bundle update rails --conservative
Use --conservative to minimize collateral gem updates.
make test
Integration tests are the most critical — they exercise the full HTTP stack. Fix any failures before proceeding.
make test 2>&1 | grep -i deprecat
Note these for fixing before the next minor bump.
Use the /commit skill. Good message example: "Upgrade Rails from 8.0.3 to 8.1.3"
Bump config.load_defaults in config/application.rb to the new minor version. Before bumping:
new_framework_defaults_X_Y.rb in Rails source).first/.last for raise_on_missing_required_finder_order_columns, path-relative redirects)make test, commit separatelyFor minor version bumps, Rails provides an update task:
bin/rails app:update
This project has minimal Rails config surface (event-sourced architecture), so this is often unnecessary. Only run if the upgrade guide mentions config changes that matter.
config/application.rb — load_defaults, config changesconfig/environments/*.rb — new or changed settingsconfig/initializers/ — framework initializers that may need updatingbin/ scripts — may need regenerationPlan a new feature end-to-end — impact analysis across all layers before delegating to /domain, /read-model, /controller skills
Create atomic git commits following project conventions
Build a new read model following project conventions (event handlers, tests, migration, configuration)
Upgrade RailsEventStore (RES) gems to a newer version
Create a new domain bounded context with aggregates, commands, events, and handlers
Scaffold a new Rails app with event sourcing, following project conventions (todomvc as reference)