A comprehensive Claude skill that helps you upgrade Ruby on Rails applications through any version from **6.0 to 8.1.1**. Built on official Rails CHANGELOGs. It analyzes your project with Claude Code's built-in file tools — no external services required. --- ## What Is This? A Claude skill that: - **Analyzes** your Rails project automatically by reading its files - **Detects** your current version and target version - **Plans** single-hop or multi-hop upgrade paths - **Identifies** breaking changes specific to your code - **Preserves** custom configurations with warnings - **Generates** comprehensive upgrade reports - **Applies** the fixes for you, editing the files directly - **Based on** official Rails CHANGELOGs from GitHub --- ## Quick Start ### 1. Install the Plugin ```bash /plugin marketplace add maquina-app/rails-claude-code /plugin install rails-upgrade-assistant@maquina ``` ### 2. Start Upgrading Say to Claude: ``` "Upgrade my Rails app to 8.1" ``` Claude will: 1. Detect your current version from `Gemfile.lock` and plan the path (single or multi-hop) 2. Generate a breaking-changes detection script and run it 3. Evaluate the findings against your actual code 4. Produce a comprehensive upgrade report with OLD → NEW examples 5. Offer to apply the fixes directly --- ## Supported Upgrade Paths | From | To | Hops | Breaking Changes | Difficulty | |------|----|----|-----------------|------------| | 8.0.x | 8.1.1 | 1 | 8 changes | Easy | | 7.2.x | 8.0.4 | 1 | 13 changes | Hard | | 7.1.x | 7.2.3 | 1 | 38 changes | Medium | | 7.0.x | 7.1.6 | 1 | 12 changes | Medium | | 6.1.x | 7.0.0 | 1 | 17 changes | Hard | | 6.0.x | 6.1.0 | 1 | 18 changes | Medium | | 6.0.x | 8.1.1 | 6 | 106 changes | Very Hard | ### Sequential Upgrades Required Rails upgrades must be sequential: ``` Correct: 6.0 → 6.1 → 7.0 → 7.1 → 7.2 → 8.0 → 8.1 Wrong: 6.0 → 7.0 (skips 6.1) ``` For multi-hop upgrades, Claude will: - Explain the sequential requirement - Plan all intermediate hops - Generate separate reports for each hop - Guide you through completing each hop before moving to next --- ## How It Works ### Full upgrade (the default) Best for understanding what needs to change before making edits. ``` "Upgrade my Rails app from 7.2 to 8.0" ``` Claude will: 1. Read `Gemfile.lock` to detect the current version 2. Load appropriate version guide(s) 3. Analyze your project files for custom code 4. Identify breaking changes affecting your code 5. Generate comprehensive upgrade report You remain in control and apply changes manually. ### Query-specific Best for specific questions about changes. ``` "What ActiveRecord changes are in Rails 8.0?" "How do I handle the SSL configuration change?" "What breaking changes affect my models?" "Will my Redis cache work after upgrading to 8.0?" ``` --- ## Key Breaking Changes by Version ### Rails 8.0 → 8.1 **High impact:** - SSL configuration now commented out (affects non-Kamal deploys) - Database `pool:` renamed to `max_connections:` - bundler-audit script required ### Rails 7.2 → 8.0 **High impact:** - Asset pipeline: Sprockets → Propshaft - Solid gems: New defaults for cache/queue/cable - Multi-database config required for Solid gems ### Rails 7.1 → 7.2 **High impact:** - Transaction-aware job enqueuing (behavior change) - `ActiveRecord::Base.connection` deprecated - `show_exceptions` changed from boolean to symbol - `Rails.application.secrets` removed ### Rails 7.0 → 7.1 **High impact:** - `cache_classes` → `enable_reloading` (inverted logic) - Force SSL now default in production - SQLite database moved to `storage/` ### Rails 6.1 → 7.0 **High impact:** - Zeitwerk autoloader required (Classic removed) - `rails` command replaces `rake` for most tasks - Spring removed from default Gemfile - `ActiveSupport::Dependencies` autoloading deprecated ### Rails 6.0 → 6.1 **High impact:** - Per-database connection handling changes - `ActiveRecord::Base#connection` pool behavior updated - Hotwire (Turbo + Stimulus) introduced as default frontend - `rails db:prepare` added as preferred setup command --- ## Custom Code Detection The skill automatically detects and warns about customizations: ### Database Configuration ```ruby # Custom SQLite path detected in config/database.yml # Current: database: db/development.sqlite3 # Rails 7.1+: database: storage/development.sqlite3 # Action: Review and update path ``` ### SSL Middleware ```ruby # Custom SSL middleware detected in config/application.rb # Line 23: middleware.use CustomSSLMiddleware # Rails 7.1+: May conflict with config.force_ssl = true # Action: Review compatibility ``` ### Autoload Paths ```ruby # Custom autoload_paths in config/application.rb # Line 15: config.autoload_paths << Rails.root.join('lib') # Rails 7.1+: lib/ autoloaded by default (config.autoload_lib) # Action: Remove manual path to avoid conflicts ``` ### Asset Pipeline ```ruby # Custom Sprockets processors detected # Files: lib/assets/processors/custom_minifier.rb # Rails 8.0+: Propshaft doesn't support processors # Action: Migrate to different approach or keep Sprockets ``` --- ## What You Get Every upgrade request generates a detailed report: **1. Executive Summary** - Current and target versions - Number of breaking changes - Estimated time and risk assessment **2. Project Analysis** - Your Rails version and structure - Files that need updating - Custom configurations detected **3. Breaking Changes (Prioritized)** - HIGH Priority: Will cause app to fail - MEDIUM Priority: Should address soon - LOW Priority: Optional improvements **4. Code Examples (OLD vs NEW)** ```ruby # OLD (Rails 7.2) config.action_dispatch.show_exceptions = true # NEW (Rails 7.2+) config.action_dispatch.show_exceptions = :all ``` **5. Step-by-Step Migration Guide** - Phase-by-phase breakdown - Time estimates per phase - Testing checkpoints **6. Testing Checklist** - Unit test guidance - Integration test scenarios - Manual testing checklist --- ## Pre-Upgrade Checklist Before starting any upgrade: **Critical:** - All tests currently passing - Database backed up - Application under version control - Staging environment available - Rollback plan documented **Important:** - Current version confirmed - Dependencies reviewed for compatibility - Custom code documented --- ## Package Contents ``` rails-upgrade-assistant/ ├── agents/rails-upgrade-assistant.md Main agent ├── workflows/ How to generate deliverables ├── examples/ Real usage scenarios ├── reference/ Quick reference ├── version-guides/ Rails version details ├── templates/ Report templates └── detection-scripts/ Pattern definitions ``` ### Version Guides - `upgrade-6.0-to-6.1.md` - 18 breaking changes - `upgrade-6.1-to-7.0.md` - 17 breaking changes - `upgrade-7.0-to-7.1.md` - 12 breaking changes - `upgrade-7.1-to-7.2.md` - 38 breaking changes - `upgrade-7.2-to-8.0.md` - 13 breaking changes - `upgrade-8.0-to-8.1.md` - 8 breaking changes --- ## Usage Examples ### Simple Upgrade ``` "Upgrade my Rails app to 8.1" ``` ### With Specific Details ``` "Upgrade my Rails app from 7.2 to 8.0" ``` ### Risk Assessment Only ``` "Assess upgrade impact from 7.2 to 8.0" ``` ### Component-Specific Questions ``` "What ActiveRecord changes are in Rails 8.0?" "Show me all configuration file changes for 7.2" ``` --- ## Next Steps

GitHub Repository

View source code and contribute.

Rails MCP Server

Optional — static code analysis to complement upgrades.