rails-upgrade
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, or querying version-specific changes. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.
ombulabs · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add ombulabs/claude-code_rails-upgrade-skill --skill rails-upgrade技能说明
name: rails-upgrade description: 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, or querying version-specific changes. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.
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_railsgem. 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_defaultsupdates 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:
- Incremental Upgrades - Always upgrade one minor/major version at a time
- Assessment First - Understand scope before making changes
- Dual-Boot Testing - Test both versions during transition using
next_railsgem - Test Coverage - Ensure adequate test coverage before upgrading (aim for 80%+)
- Gem Compatibility - Check gem compatibility at each step using RailsBump
- Deprecation Warnings - Address deprecations before upgrading
- Backwards Compatible Changes - Deploy small changes to production before version bump
Key Resources:
- DELEGATE to the
dual-bootskill for dual-boot setup withnext_rails(see Dependencies) - See
references/deprecation-warnings.mdfor managing deprecations - See
references/staying-current.mdfor 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):
- Explain the sequential requirement
- Break it into individual hops
- Generate separate reports for each hop
- 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 | Transacti |