skill-rails-upgrade

Rails Upgrade Analyzer - Intelligent Rails Upgrade Assessment Assistant

Skill Overview

Rails Upgrade Analyzer is an intelligent assistant specifically designed to analyze Ruby on Rails applications and generate a comprehensive upgrade assessment report. It can automatically detect your current Rails version, fetch the latest version information, and provide optional file-merging plans to help you upgrade the framework safely and controllably.

Use Cases

1. Comprehensive Pre-Upgrade Version Assessment

Before upgrading Rails, it’s crucial to understand the differences between your current version and the target version. This skill analyzes your Gemfile.lock and Gemfile to extract the exact current version, retrieve the latest stable version, and categorize the upgrade type (patch upgrade, minor version upgrade, or major version upgrade). It also pulls relevant change information from the official Rails upgrade guides and railsdiff.org to give you a complete assessment of upgrade complexity.

2. Selective Upgrades That Protect Local Configuration

The traditional rails app:update command overwrites configuration files directly, which may cause you to lose your local customizations. Rails Upgrade Analyzer uses an intelligent merge strategy: it first detects your locally customized files (such as i18n configuration, mail settings, custom boot scripts, etc.), and then—based on railsdiff—analyzes the impact of each changed file, categorizing them as “new file,” “safe overwrite,” “manual merge needed,” or “can be skipped.” This ensures your important configuration won’t be accidentally overwritten.

3. Full Checks Across the Dependency Ecosystem

Rails upgrades involve not only the framework itself, but also JavaScript dependencies and database migrations. This skill checks the package manager used in your project (npm/yarn/importmap), identifies Rails-related JavaScript packages (such as @hotwired/turbo-rails, @rails/actioncable, etc.), and provides version-alignment recommendations. It also reminds you to run new database migrations and, after the upgrade, provides a complete validation checklist.

Core Features

1. Version Difference Analysis

Using the GitHub CLI, it automatically retrieves the latest Rails release version and compares it with your current version to determine the upgrade type. At the same time, it scrapes the official Rails upgrade guides and railsdiff.org for detailed change information, extracting breaking changes, deprecation warnings, configuration changes, and any required migration actions relevant to your upgrade path.

2. Selective File Merging

Instead of the overwriting behavior of rails app:update, it uses an intelligent merge process. First, it detects locally customized files via the git status. Then, based on railsdiff, it analyzes the change type for each file. For files that require manual merging, it provides clear comparisons: keep your local customizations, add only the necessary new Rails functionality, and remove deprecated settings.

3. Upgrade Complexity Assessment

Based on the version span, number of breaking changes, extent of configuration changes, deprecation handling requirements, and the scope of dependency updates, the upgrade is classified as “small,” “medium,” or “large,” along with recommended upgrade steps and considerations.

Frequently Asked Questions

How can I upgrade Rails safely?

The upgrade process recommended by Rails Upgrade Analyzer is: first ensure the test suite passes and review deprecation warnings from the current version; then update the Gemfile and run bundle update rails; update JavaScript dependencies; use this skill’s selective merge process instead of running rails app:update directly; run database migrations; finally run the test suite and review deprecated code. Throughout the process, git history remains traceable, and any step can be rolled back.

Will a Rails upgrade overwrite my configuration files?

The traditional rails app:update does overwrite configuration files. However, this skill uses a protective strategy. It first detects your local customizations (such as i18n configuration, mailer settings, custom bin scripts, etc.), then handles items by category: new files are created directly; unmodified standard files can be safely overwritten; files with local customizations are manually merged—adding only the necessary new features and preserving all your customizations. Before executing the upgrade, it shows you a complete change plan for confirmation.

What should I watch out for when upgrading Rails from 7 to 8?

Major version upgrades typically involve more breaking changes. Rails Upgrade Analyzer automatically fetches the Rails 8 upgrade guide and extracts key changes, such as new framework defaults, configuration file format changes, removed methods, and newly required dependencies. For upgrades from Rails 7 to 8, pay special attention to changes in the JavaScript ecosystem (such as aligning Turbo and Stimulus versions), Active Record API changes, and any adjustments that may be needed to test code. The skill provides a detailed change checklist and step-by-step validation guidance.