Skip to content

ombulabs/claude-code_rails-upgrade-skill / rails-upgrade

rails-upgrade

Verified

Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, querying version-specific changes, or answering what stands between the app and the next Rails version. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.

FileKindSize
SKILL.mdskill md11.0 KB
detection-scripts/gem_limits.rbscript6.0 KB
detection-scripts/hop.rbscript2.2 KB
detection-scripts/patterns/rails-40-patterns.expectations.ymlconfig43.8 KB
detection-scripts/patterns/rails-40-patterns.ymlconfig96.5 KB
detection-scripts/patterns/rails-41-patterns.expectations.ymlconfig25.6 KB
detection-scripts/patterns/rails-41-patterns.ymlconfig59.8 KB
detection-scripts/patterns/rails-42-patterns.expectations.ymlconfig27.5 KB
detection-scripts/patterns/rails-42-patterns.ymlconfig48.7 KB
detection-scripts/patterns/rails-50-patterns.expectations.ymlconfig1.9 KB
detection-scripts/patterns/rails-50-patterns.ymlconfig8.1 KB
detection-scripts/patterns/rails-51-patterns.expectations.ymlconfig4.2 KB
detection-scripts/patterns/rails-51-patterns.ymlconfig15.0 KB
detection-scripts/patterns/rails-52-patterns.expectations.ymlconfig5.0 KB
detection-scripts/patterns/rails-52-patterns.ymlconfig14.7 KB
detection-scripts/patterns/rails-60-patterns.expectations.ymlconfig1007 B
detection-scripts/patterns/rails-60-patterns.ymlconfig14.2 KB
detection-scripts/patterns/rails-70-patterns.expectations.ymlconfig4.0 KB
detection-scripts/patterns/rails-70-patterns.ymlconfig11.2 KB
detection-scripts/patterns/rails-71-patterns.expectations.ymlconfig3.1 KB
detection-scripts/patterns/rails-71-patterns.ymlconfig9.5 KB
detection-scripts/patterns/rails-72-patterns.expectations.ymlconfig1.2 KB
detection-scripts/patterns/rails-72-patterns.ymlconfig6.1 KB
detection-scripts/patterns/rails-80-patterns.expectations.ymlconfig6.6 KB
detection-scripts/patterns/rails-80-patterns.ymlconfig21.2 KB
detection-scripts/patterns/rails-81-patterns.expectations.ymlconfig4.3 KB
detection-scripts/patterns/rails-81-patterns.ymlconfig13.2 KB
detection-scripts/scan_patterns.rbscript42.8 KB
examples/multi-hop-upgrade.mdmarkdown18.9 KB
examples/simple-upgrade.mdmarkdown4.0 KB
references/breaking-changes-by-version-reference.mdmarkdown3.9 KB
references/deprecation-warnings-reference.mdmarkdown10.7 KB
references/gem-compatibility-reference.mdmarkdown8.2 KB
references/js-compressor-sprockets-mismatch-reference.mdmarkdown4.7 KB
references/multi-hop-strategy-reference.mdmarkdown8.8 KB
references/next-hop-readiness-reference.mdmarkdown2.1 KB
references/no-test-suite-smoke-reference.mdmarkdown4.7 KB
references/request-patterns-reference.mdmarkdown3.7 KB
references/sequential-strategy-reference.mdmarkdown2.1 KB
references/staying-current-reference.mdmarkdown7.8 KB
references/testing-checklist-reference.mdmarkdown6.3 KB
templates/app-update-preview-template.mdmarkdown4.3 KB
templates/upgrade-report-template.mdmarkdown10.2 KB
version-guides/upgrade-3.2-to-4.0.mdmarkdown68.0 KB
version-guides/upgrade-4.0-to-4.1.mdmarkdown66.7 KB
version-guides/upgrade-4.1-to-4.2.mdmarkdown60.7 KB
version-guides/upgrade-4.2-to-5.0.mdmarkdown9.7 KB
version-guides/upgrade-5.0-to-5.1.mdmarkdown19.1 KB
version-guides/upgrade-5.1-to-5.2.mdmarkdown17.7 KB
version-guides/upgrade-5.2-to-6.0.mdmarkdown6.4 KB
version-guides/upgrade-6.0-to-6.1.mdmarkdown6.8 KB
version-guides/upgrade-6.1-to-7.0.mdmarkdown14.7 KB
version-guides/upgrade-7.0-to-7.1.mdmarkdown13.2 KB
version-guides/upgrade-7.1-to-7.2.mdmarkdown11.2 KB
version-guides/upgrade-7.2-to-8.0.mdmarkdown23.1 KB
version-guides/upgrade-8.0-to-8.1.mdmarkdown14.0 KB
workflows/00-verify-latest-patch-workflow.mdmarkdown1.7 KB
workflows/01-run-test-suite-workflow.mdmarkdown12.7 KB
workflows/02-resolve-deprecation-warnings-workflow.mdmarkdown6.3 KB
workflows/03-validate-upgrade-path-workflow.mdmarkdown1.8 KB
workflows/04-setup-next-rails-workflow.mdmarkdown1.5 KB
workflows/05-detect-breaking-changes-workflow.mdmarkdown20.0 KB
workflows/06-check-gem-compatibility-workflow.mdmarkdown11.1 KB
workflows/07-boot-smoke-test-workflow.mdmarkdown7.3 KB
workflows/08-generate-upgrade-report-workflow.mdmarkdown12.7 KB
workflows/09-generate-app-update-preview-workflow.mdmarkdown7.3 KB
workflows/10-implement-and-upgrade-workflow.mdmarkdown2.5 KB
workflows/11-sync-ci-workflow.mdmarkdown8.6 KB
workflows/12-align-load-defaults-workflow.mdmarkdown952 B
workflows/13-mention-cleanup-workflow.mdmarkdown1.3 KB

examples/multi-hop-upgrade.md

View on GitHub
# Example: Multi-Hop Upgrade

**Scenario:** Upgrading from Rails 5.2 to Rails 8.0

---

## User Request

"Help me upgrade my Rails app from 5.2 to 8.0"

---

## Claude Response

### Important: Sequential Upgrade Required

I'll help you upgrade from Rails 5.2 to 8.0! This is a multi-hop upgrade that requires going through each version sequentially. **You cannot skip versions.**

### Your Upgrade Path

```
5.2 → 6.0 → 6.1 → 7.0 → 7.1 → 7.2 → 8.0
 |     |     |     |     |     |
Hop1  Hop2  Hop3  Hop4  Hop5  Hop6
```

### Estimated Timeline

| Hop | From → To | Difficulty | Time | Key Challenge |
|-----|-----------|------------|------|---------------|
| 1 | 5.2 → 6.0 | Hard | 1-2 weeks | Zeitwerk autoloader |
| 2 | 6.0 → 6.1 | Medium | 3-5 days | Minor changes |
| 3 | 6.1 → 7.0 | Hard | 1-2 weeks | Hotwire/Turbo |
| 4 | 7.0 → 7.1 | Medium | 3-5 days | Composite keys |
| 5 | 7.1 → 7.2 | Medium | 3-5 days | Transaction jobs |
| 6 | 7.2 → 8.0 | Very Hard | 1-2 weeks | Propshaft |

**Total Estimated Time:** 6-10 weeks

### Ruby Upgrade Required

Before starting, you'll need to upgrade Ruby:
- Rails 5.2: Ruby 2.2.2+
- Rails 6.0: Ruby 2.5.0+ required
- Rails 7.0: Ruby 2.7.0+ required
- Rails 7.2+: Ruby 3.1.0+ recommended
- Rails 8.0: Ruby 3.1.0+ required

**Recommended:** Upgrade to Ruby 3.2+ before starting.

### My Recommendation

1. **Upgrade Ruby first** to 3.2+
2. **Complete Hop 1 (5.2 → 6.0)** - This is the biggest change
3. **Quick hops through 6.1 → 7.0** - Focus on Hotwire migration
4. **Finish with 7.x → 8.0** - Asset pipeline migration

---

Hop 1: Rails 5.2 → 6.0 (Hard — ~1–2 weeks)

Breaking Changes Found in Your Code

┌──────────┬───────────────────────┬──────┬──────────────────────────┬─────────────────────────┐
│ Priority │         File          │ Line │          Issue           │           Fix           │
├──────────┼───────────────────────┼──────┼──────────────────────────┼─────────────────────────┤
│ 🟡 MED   │ config/application.rb │ 22   │ config.load_defaults 5.1 │ Update to 5.2, then 6.0 │
└──────────┴───────────────────────┴──────┴──────────────────────────┴─────────────────────────┘

Zeitwerk Check (⚠️  Most Critical)

No require_dependency calls found in your codebase. However, you must run this after updating Rails:

bundle exec rails zeitwerk:check

This will surface any file naming mismatches that the classic autoloader was silently tolerating.

Gem Updates Required

┌─────────────┬───────────┬─────────────────┐
│     Gem     │  Current  │ Minimum for 6.0 │
├─────────────┼───────────┼─────────────────┤
│ rspec-rails │ ~> 3.5.0  │ 4.0.0           │
├─────────────┼───────────┼─────────────────┤
│ sidekiq     │ ~> 5.0    │ 6.0.0           │
├─────────────┼───────────┼─────────────────┤
│ capybara    │ ~> 2.13.0 │ 3.x             │
└─────────────┴───────────┴─────────────────┘

Migration Steps

git checkout -b rails-60-upgrade
# 1. Update Gemfile: gem 'rails', '~> 6.0.0'
# 2. Update gem constraints above
bundle update rails
bundle exec rails app:update
bundle exec rails zeitwerk:check
bundle exec rspec

---

Hop 2: Rails 6.0 → 6.1 (Medium — ~3–5 days)

Breaking Changes Found in Your Code

┌──────────┬───────────────────────────────────┬──────┬─────────────────────────────────────────────────────────────────┬────────────────────┐
│ Priority │               File                │ Line │                              Issue                              │        Fix         │
├──────────┼───────────────────────────────────┼──────┼─────────────────────────────────────────────────────────────────┼────────────────────┤
│ 🟡 MED   │ app/views/contacts/_form.html.erb │ 1    │ form_with(model: contact, local: true) — local: true deprecated │ Remove local: true │
└──────────┴───────────────────────────────────┴──────┴─────────────────────────────────────────────────────────────────┴────────────────────┘

No other issues detected. Minor steps:

git checkout -b rails-61-upgrade
# Update Gemfile: gem 'rails', '~> 6.1.0'
bundle update rails
bundle exec rails app:update
# Update config.load_defaults to 6.1
bundle exec rspec

---

Hop 3: Rails 6.1 → 7.0 (Hard — ~1–2 weeks)

⚠️  This is the most impactful hop for your frontend
Breaking Changes Found in Your Code

┌──────────┬────────────────────────────────────────┬──────┬────────────────────────────────────────┬───────────────────────────────────────────┐
│ Priority │                  File                  │ Line │                 Issue                  │                    Fix                    │
├──────────┼────────────────────────────────────────┼──────┼────────────────────────────────────────┼───────────────────────────────────────────┤
│ 🔴 HIGH  │ Gemfile                                │ 31   │ gem 'turbolinks', '~> 5'               │ Replace with gem 'turbo-rails'            │
├──────────┼────────────────────────────────────────┼──────┼────────────────────────────────────────┼───────────────────────────────────────────┤
│ 🔴 HIGH  │ app/views/layouts/application.html.erb │ 7, 9 │ 'data-turbolinks-track': 'reload'      │ Keep as-is — still valid with turbo-rails │
├──────────┼────────────────────────────────────────┼──────┼────────────────────────────────────────┼───────────────────────────────────────────┤
│ 🔴 HIGH  │ app/assets/javascripts/application.js  │ 14   │ //= require turbolinks                 │ Remove this line                          │
└──────────┴────────────────────────────────────────┴──────┴────────────────────────────────────────┴───────────────────────────────────────────┘

Gemfile Changes

# Remove
gem 'turbolinks', '~> 5'

# Add
gem 'turbo-rails'
gem 'stimulus-rails'
JavaScript Changes

Migration Steps

git checkout -b rails-70-upgrade
# Make all JS changes above
# Update Gemfile
bundle update rails
bundle exec rails app:update
# Update config.load_defaults to 7.0
bundle exec rspec
# Manual test: navigate through the app, verify JS events fire

---

Hop 4: Rails 7.0 → 7.1 (Medium — ~3–5 days)

Breaking Changes Found in Your Code

┌──────────┬───────────────────────────────────┬──────┬───────────────────────────────────────────────┬───────────────────────────────────────────┐
│ Priority │               File                │ Line │                     Issue                     │                    Fix                    │
├──────────┼───────────────────────────────────┼──────┼───────────────────────────────────────────────┼───────────────────────────────────────────┤
│ 🔴 HIGH  │ config/environments/production.rb │ 5    │ config.cache_classes = true — replaced in 7.1 │ Change to config.enable_reloading = false │
├──────────┼───────────────────────────────────┼──────┼───────────────────────────────────────────────┼───────────────────────────────────────────┤
│ 🔴 HIGH  │ config/environments/test.rb       │ 8    │ config.cache_classes = true — replaced in 7.1 │ Change to config.enable_reloading = false │
└──────────┴───────────────────────────────────┴──────┴───────────────────────────────────────────────┴───────────────────────────────────────────┘

▎ Note: enable_reloading is the inverse of cache_classes. cache_classes = true → enable_reloading = false.

Also check config/environments/development.rb for config.cache_classes = false → enable_reloading = true.

Migration Steps

git checkout -b rails-71-upgrade
# Replace cache_classes with enable_reloading (inverted)
bundle update rails
bundle exec rails app:update
# Update config.load_defaults to 7.1
bundle exec rspec

---

Hop 5: Rails 7.1 → 7.2 (Medium — ~3–5 days)

Breaking Changes Found in Your Code

┌──────────┬─────────────────────────────┬──────┬────────────────────────────────────────────────┬─────────────────┐
│ Priority │            File             │ Line │                     Issue                      │       Fix       │
├──────────┼─────────────────────────────┼──────┼────────────────────────────────────────────────┼─────────────────┤
│ 🔴 HIGH  │ config/environments/test.rb │ 26   │ config.action_dispatch.show_exceptions = false │ Change to :none │
└──────────┴─────────────────────────────┴──────┴────────────────────────────────────────────────┴─────────────────┘

Fix

# BEFORE
config.action_dispatch.show_exceptions = false

# AFTER
config.action_dispatch.show_exceptions = :none

Migration Steps

git checkout -b rails-72-upgrade
# Fix show_exceptions
bundle update rails
bundle exec rails app:update
# Update config.load_defaults to 7.2
bundle exec rspec

---

Hop 6: Rails 7.2 → 8.0 (Very Hard — ~1–2 weeks)

Asset Pipeline Decision Required

Your app uses Sprockets (sprockets/railtie in config/application.rb:12). Rails 8.0 defaults to Propshaft, but Sprockets still works. You have two options:

Option A — Keep Sprockets (recommended for this app):

# Gemfile — explicitly keep it
gem 'sprockets-rails'

No other asset changes needed. Your config.assets.js_compressor, config.assets.compile, etc. all stay.

Option B — Migrate to Propshaft (more work, cleaner long-term):

- Remove sprockets/railtie from application.rb
- Remove sprockets-rails, sassc-rails from Gemfile
- Add gem 'propshaft'
- Remove Sprockets-specific asset configs from production.rb
- Add cssbundling-rails if using Sass

Solid Gems Decision

Your app uses Sidekiq for jobs, which still works in Rails 8.0. No migration needed unless you want to switch to Solid Queue.

┌───────────────────────────────────┬───────────────────┬────────────────┐
│              Current              │ Rails 8.0 Default │ Recommendation │
├───────────────────────────────────┼───────────────────┼────────────────┤
│ Sidekiq (jobs)                    │ Solid Queue       │ Keep Sidekiq   │
├───────────────────────────────────┼───────────────────┼────────────────┤
│ File caching                      │ Solid Cache       │ Keep existing  │
├───────────────────────────────────┼───────────────────┼────────────────┤
│ ActionCable (no Redis configured) │ Solid Cable       │ Evaluate       │
└───────────────────────────────────┴───────────────────┴────────────────┘

Gem Updates Required

┌─────────────┬────────────────────┬─────────────────┐
│     Gem     │      Current       │ Minimum for 8.0 │
├─────────────┼────────────────────┼─────────────────┤
│ rspec-rails │ (updated in hop 1) │ 6.0.0           │
├─────────────┼────────────────────┼─────────────────┤
│ sidekiq     │ (updated in hop 1) │ 7.0.0           │
├─────────────┼────────────────────┼─────────────────┤
│ capybara    │ (updated in hop 1) │ 3.39.0          │
└─────────────┴────────────────────┴─────────────────┘

New Configuration

# config/environments/production.rb — add:
config.assume_ssl = true  # needed if behind load balancer (Heroku, etc.)

Migration Steps

git checkout -b rails-80-upgrade
# Decide on Sprockets vs Propshaft
# Add gem 'sprockets-rails' if keeping Sprockets
bundle update rails
bundle exec rails app:update
# Update config.load_defaults to 8.0
# Add config.assume_ssl = true to production.rb
# Delete config.read_encrypted_secrets from production.rb (removed in 8.0, the 7.2 side warns)
bundle exec rspec
# Test asset serving manually

---

## Milestone Tracking

Track your progress through each hop:

### Hop 1: 5.2 → 6.0 (Zeitwerk)
- [ ] Ruby upgraded to 2.5+
- [ ] require_dependency removed
- [ ] Zeitwerk compatible naming
- [ ] update_attributes → update
- [ ] All tests passing
- [ ] Deployed to staging

### Hop 2: 6.0 → 6.1
- [ ] Rails 6.1 in Gemfile
- [ ] load_defaults 6.1
- [ ] All tests passing
- [ ] Deployed to staging

### Hop 3: 6.1 → 7.0 (Hotwire)
- [ ] Ruby upgraded to 2.7+
- [ ] Webpacker → Import Maps/jsbundling
- [ ] Turbolinks → Turbo
- [ ] rails-ujs removed
- [ ] All tests passing
- [ ] Deployed to staging

### Hop 4: 7.0 → 7.1
- [ ] Rails 7.1 in Gemfile
- [ ] load_defaults 7.1
- [ ] All tests passing
- [ ] Deployed to staging

### Hop 5: 7.1 → 7.2
- [ ] Transaction-aware jobs handled
- [ ] show_exceptions updated
- [ ] secrets → credentials
- [ ] All tests passing
- [ ] Deployed to staging

### Hop 6: 7.2 → 8.0 (Propshaft)
- [ ] Ruby upgraded to 3.1+
- [ ] Sprockets → Propshaft (or keep Sprockets)
- [ ] SSL config updated
- [ ] All tests passing
- [ ] Deployed to staging
- [ ] 🎉 UPGRADE COMPLETE!

---

## Tips for Multi-Hop Success

1. **Complete each hop fully** before starting the next
2. **Deploy to staging** after each hop
3. **Run production for 1-2 weeks** on each version if possible
4. **Fix deprecation warnings** as you go
5. **Update gems incrementally** with each Rails version
6. **Keep detailed notes** of changes made
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall