rails-upgrade

Rails Upgrade Assistant Skill

Skill Identity

• Name: Rails Upgrade Assistant
• Purpose: Intelligent Rails application upgrades from 2.3 through 8.1
• Skill Type: Modular with external workflows and examples
• Upgrade Strategy: Sequential only (no version skipping)
• Methodology: Based on FastRuby.io upgrade best practices and "The Complete Guide to Upgrade Rails" ebook
• Attribution: Content based on "The Complete Guide to Upgrade Rails" by FastRuby.io (OmbuLabs)

Dependencies

• dual-boot skill (github.com/ombulabs/claude-code_dual-boot-skill) — Sets up and manages dual-boot environments using the next_rails gem. Covers setup, NextRails.next? code patterns, CI configuration, and post-upgrade cleanup. Must be installed for Step 2 of the upgrade workflow.
• rails-load-defaults skill (github.com/ombulabs/claude-code_rails-load-defaults-skill) — Handles incremental load_defaults updates with tiered risk assessment (Tier 1: low-risk, Tier 2: needs codebase grep, Tier 3: requires human review). Used as the final step after the Rails version upgrade is complete.

Core Methodology (FastRuby.io Approach)

This skill follows the proven FastRuby.io upgrade methodology:

1. Incremental Upgrades - Always upgrade one minor/major version at a time
2. Assessment First - Understand scope before making changes
3. Dual-Boot Testing - Test both versions during transition using next_rails gem
4. Test Coverage - Ensure adequate test coverage before upgrading (aim for 80%+)
5. Gem Compatibility - Check gem compatibility at each step using RailsBump
6. Deprecation Warnings - Address deprecations before upgrading
7. Backwards Compatible Changes - Deploy small changes to production before version bump

Key Resources:

• DELEGATE to the dual-boot skill for dual-boot setup with next_rails (see Dependencies)
• See references/deprecation-warnings.md for managing deprecations
• See references/staying-current.md for maintaining upgrades over time

CRITICAL: Dual-Boot Code Pattern with NextRails.next?

When proposing code fixes that must work with both the current and target Rails versions (dual-boot), always use NextRails.next? from the next_rails gem — never use respond_to? or other feature-detection patterns.

DELEGATE to the dual-boot skill for:

• Setup and initialization (next_rails --init, Gemfile.next)
• NextRails.next? code patterns and examples
• CI configuration for dual-boot testing
• Post-upgrade cleanup (removing dual-boot branches)

DEPENDENCY: Requires the dual-boot skill

Trigger Patterns

Claude should activate this skill when user says:

Upgrade Requests:

• "Upgrade my Rails app to [version]"
• "Help me upgrade from Rails [x] to [y]"
• "What breaking changes are in Rails [version]?"
• "Plan my upgrade from [x] to [y]"
• "What Rails version am I using?"
• "Analyze my Rails app for upgrade"
• "Find breaking changes in my code"
• "Check my app for Rails [version] compatibility"

Specific Report Requests:

• "Show me the app:update changes"
• "Preview configuration changes for Rails [version]"
• "Generate the upgrade report"
• "What will change if I upgrade?"

Upgrade Cleanup Requests (delegate to the upgrade-cleanup plugin):

• "Finish the upgrade"
• "Clean up after my Rails upgrade"
• "Remove the dual-boot setup"
• "Drop the NextRails branches"
• "We're done upgrading to Rails [version]"

CRITICAL: Sequential Upgrade Strategy

⚠️ Version Skipping is NOT Allowed

Rails upgrades MUST follow a sequential path. Examples:

For Rails 5.x to 8.x:

5.0.x → 5.1.x → 5.2.x → 6.0.x → 6.1.x → 7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x

You CANNOT skip versions. Examples:

• ❌ 5.2 → 6.1 (skips 6.0)
• ❌ 6.0 → 7.0 (skips 6.1)
• ❌ 7.0 → 8.0 (skips 7.1 and 7.2)
• ✅ 5.2 → 6.0 (correct)
• ✅ 7.0 → 7.1 (correct)
• ✅ 7.2 → 8.0 (correct)

If user requests a multi-hop upgrade (e.g., 5.2 → 8.1):

1. Explain the sequential requirement
2. Break it into individual hops
3. Generate separate reports for each hop
4. Recommend completing each hop fully before moving to next

Supported Upgrade Paths

Legacy Rails (2.3 - 4.2)

| From | To | Difficulty | Key Changes | Ruby Required | |------|-----|-----------|-------------|---------------| | 2.3.x | 3.0.x | Very Hard | XSS protection, routes syntax | 1.8.7 - 1.9.3 | | 3.0.x | 3.1.x | Medium | Asset pipeline, jQuery | 1.8.7 - 1.9.3 | | 3.1.x | 3.2.x | Easy | Ruby 1.9.3 support | 1.8.7 - 2.0 | | 3.2.x | 4.0.x | Hard | Strong Parameters, Turbolinks | 1.9.3+ | | 4.0.x | 4.1.x | Medium | Spring, secrets.yml | 1.9.3+ | | 4.1.x | 4.2.x | Medium | ActiveJob, Web Console | 1.9.3+ | | 4.2.x | 5.0.x | Hard | ActionCable, API mode, ApplicationRecord | 2.2.2+ |

Modern Rails (5.0 - 8.1)

| From | To | Difficulty | Key Changes | Ruby Required | |------|-----|-----------|-------------|---------------| | 5.0.x | 5.1.x | Easy | Encrypted secrets, yarn default | 2.2.2+ | | 5.1.x | 5.2.x | Medium | Active Storage, credentials | 2.2.2+ | | 5.2.x | 6.0.x | Hard | Zeitwerk, Action Mailbox/Text | 2.5.0+ | | 6.0.x | 6.1.x | Medium | Horizontal sharding, strict loading | 2.5.0+ | | 6.1.x | 7.0.x | Hard | Hotwire/Turbo, Import Maps | 2.7.0+ | | 7.0.x | 7.1.x | Medium | Composite keys, async queries | 2.7.0+ | | 7.1.x | 7.2.x | Medium | Transaction-aware jobs, DevContainers | 3.1.0+ | | 7.2.x | 8.0.x | Very Hard | Propshaft, Solid gems, Kamal | 3.2.0+ | | 8.0.x | 8.1.x | Easy | Bundler-audit, max_connections | 3.2.0+ |

Available Resources

Core Documentation

• SKILL.md - This file (entry point)

Version-Specific Guides (Load as needed)

Legacy Rails:

• version-guides/upgrade-3.2-to-4.0.md - Rails 3.2 → 4.0 (Strong Parameters)
• version-guides/upgrade-4.0-to-4.1.md - Rails 4.0 → 4.1 (Spring, secrets.yml, enums)
• version-guides/upgrade-4.1-to-4.2.md - Rails 4.1 → 4.2 (ActiveJob, Web Console)
• version-guides/upgrade-4.2-to-5.0.md - Rails 4.2 → 5.0 (ApplicationRecord)

Modern Rails:

• version-guides/upgrade-5.0-to-5.1.md - Rails 5.0 → 5.1 (Encrypted secrets)
• version-guides/upgrade-5.1-to-5.2.md - Rails 5.1 → 5.2 (Active Storage, Credentials)
• version-guides/upgrade-5.2-to-6.0.md - Rails 5.2 → 6.0 (Zeitwerk)
• version-guides/upgrade-6.0-to-6.1.md - Rails 6.0 → 6.1 (Horizontal sharding)
• version-guides/upgrade-6.1-to-7.0.md - Rails 6.1 → 7.0 (Hotwire/Turbo)
• version-guides/upgrade-7.0-to-7.1.md - Rails 7.0 → 7.1 (Composite keys)
• version-guides/upgrade-7.1-to-7.2.md - Rails 7.1 → 7.2 (Transaction jobs)
• version-guides/upgrade-7.2-to-8.0.md - Rails 7.2 → 8.0 (Propshaft)
• version-guides/upgrade-8.0-to-8.1.md - Rails 8.0 → 8.1 (bundler-audit)

Workflow Guides (Load when generating deliverables)

• workflows/test-suite-verification-workflow.md - MANDATORY FIRST STEP - How to run and verify test suite
• workflows/direct-detection-workflow.md - How to run breaking change detection directly
• workflows/upgrade-report-workflow.md - How to generate upgrade reports
• workflows/gem-compatibility-workflow.md - Load in Step 4.5 - Per-lockfile gem compatibility check against the target Rails version. Documents both the primary (next_rails bundle_report compatibility) and the secondary (railsbump.org API) and the rules for when to escalate.
• workflows/boot-smoke-test-workflow.md - Load in Step 4.6 - Run a Rails-loading command against Gemfile.next to catch gem-level runtime incompat that the resolver can't see (gems calling removed Rails internals or require-ing removed files).
• workflows/ci-sync-workflow.md - MANDATORY before opening the upgrade PR - How to verify CI config matches the upgraded Gemfile
• `workflows/a