Rails应用升级分析器 - 自动化评估与升级指南

skill-rails-upgrade by sickn33/antigravity-awesome-skills

141 周安装量

31,300 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill skill-rails-upgrade

软件维护自动化 Ruby on Rails

🇨🇳中文介绍

何时使用此技能

分析 Rails 应用并提供升级评估

在处理分析 Rails 应用并提供升级评估时使用此技能。

Rails 升级分析器

分析当前的 Rails 应用程序，并提供包含选择性文件合并的全面升级评估。

步骤 1：验证 Rails 应用程序

通过查找以下文件来检查我们是否在 Rails 应用程序中：

Gemfile（必须存在且包含 'rails'）
config/application.rb（Rails 应用程序配置）
config/environment.rb（Rails 环境）

如果缺少其中任何一个文件或文件内容未表明是 Rails 应用，请停止并告知用户这似乎不是一个 Rails 应用程序。

步骤 2：获取当前 Rails 版本

从以下位置提取当前 Rails 版本：

首先，检查 Gemfile.lock 以获取确切的已安装版本（查找 rails (x.y.z)）
如果未找到，则检查 Gemfile 中的版本约束

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 3：查找最新的 Rails 版本

使用 GitHub CLI 获取最新的 Rails 发布版本：

gh api repos/rails/rails/releases/latest --jq '.tag_name'

这将返回最新的稳定版本标签（例如，v8.0.1）。为了比较，请去掉 'v' 前缀。

同时检查最近的标签以了解发布情况：

gh api repos/rails/rails/tags --jq '.[0:10] | .[].name'

步骤 4：确定升级类型

比较当前版本和最新版本以对升级进行分类：

补丁升级：主版本和次版本相同，补丁版本不同（例如，7.1.3 → 7.1.5）
次版本升级：主版本相同，次版本不同（例如，7.1.3 → 7.2.0）
主版本升级：主版本不同（例如，7.1.3 → 8.0.0）

步骤 5：获取升级指南

使用 WebFetch 获取官方的 Rails 升级指南：

URL: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html

查找与版本跨越相关的部分。该指南按目标版本组织，包含以下部分：

"从 Rails X.Y 升级到 Rails X.Z"
破坏性变更
弃用警告
配置变更
必需的迁移

提取并总结与用户特定升级路径相关的部分。

步骤 6：获取 Rails 差异

使用 WebFetch 从 railsdiff.org 获取版本间的差异：

URL: https://railsdiff.org/{current_version}/{target_version}

例如：https://railsdiff.org/7.1.3/8.0.0

默认配置文件的变更
需要添加的新文件
修改的初始化器
更新的依赖项
bin/ 脚本的变更

总结关键的文件变更。

步骤 7：检查 JavaScript 依赖项

Rails 应用程序通常包含应随 Rails 一起更新的 JavaScript 包。检查并报告这些依赖项。

7.1：识别 JS 包管理器

检查应用程序使用哪个包管理器：

# 检查是否存在 package.json (npm/yarn)
ls package.json 2>/dev/null

# 检查是否存在 importmap (Rails 7+)
ls config/importmap.rb 2>/dev/null

7.2：检查与 Rails 相关的 JS 包

如果存在 package.json，检查以下与 Rails 相关的包：

# 提取与 Rails 相关的包的当前版本
cat package.json | grep -E '"@hotwired/|"@rails/|"stimulus"|"turbo-rails"' || echo "未找到 Rails JS 包"

需要检查的关键包：

包	用途	版本对齐
`@hotwired/turbo-rails`	Turbo Drive/Frames/Streams	应与 Rails 版本时代匹配
`@hotwired/stimulus`	Stimulus JS 框架	通常在 Rails 版本间保持稳定
`@rails/actioncable`	WebSocket 支持	应与 Rails 版本匹配
`@rails/activestorage`	直接上传	应与 Rails 版本匹配
`@rails/actiontext`	富文本编辑	应与 Rails 版本匹配
`@rails/request.js`	Rails UJS 替代品	应与 Rails 版本时代匹配

对于 npm/yarn 项目，检查可用的更新：

# 使用 npm
npm outdated @hotwired/turbo-rails @hotwired/stimulus @rails/actioncable @rails/activestorage 2>/dev/null

# 或直接检查最新版本
npm view @hotwired/turbo-rails version 2>/dev/null
npm view @rails/actioncable version 2>/dev/null

7.4：检查 Importmap 固定版本（如果适用）

如果应用程序使用 importmap-rails，检查 config/importmap.rb 中的固定版本：

cat config/importmap.rb | grep -E 'pin.*turbo|pin.*stimulus|pin.*@rails' || echo "未找到 importmap 固定版本"

更新 importmap 固定版本：

bin/importmap pin @hotwired/turbo-rails
bin/importmap pin @hotwired/stimulus

7.5：JS 依赖项摘要

在升级摘要中包含：

### JavaScript 依赖项

**包管理器**: [npm/yarn/importmap/无]

| 包 | 当前版本 | 最新版本 | 操作 |
|---------|---------|--------|--------|
| @hotwired/turbo-rails | 8.0.4 | 8.0.12 | 建议更新 |
| @rails/actioncable | 7.1.0 | 8.0.0 | 随 Rails 更新 |
| ... | ... | ... | ... |

**推荐的 JS 更新：**
- 运行 `npm update @hotwired/turbo-rails`（或 yarn 等效命令）
- 运行 `npm update @rails/actioncable @rails/activestorage` 以匹配 Rails 版本

步骤 8：生成升级摘要

提供包含步骤 1-7 所有发现的全面摘要：

当前版本：X.Y.Z
最新版本：A.B.C
升级类型：[补丁/次版本/主版本]

升级复杂度评估

根据以下因素将升级评级为小、中或大：

因素	小	中	大
版本跨越	仅补丁	次版本	主版本
破坏性变更	无	少量，文档完善	许多，重大
配置变更	最少	中等	广泛
弃用项	无活跃项	一些需要处理	许多需要重构
依赖项	兼容	需要一些更新	主要依赖项更新

需要处理的关键变更

列出用户需要处理的最重要变更：

配置文件更新
需要更新的已弃用方法/功能
新的必需依赖项
所需的数据库迁移
破坏性的 API 变更

何时使用此技能

分析 Rails 应用并提供升级评估

在处理分析 Rails 应用并提供升级评估时使用此技能。

步骤 9：选择性文件更新（替代 `rails app:update`）

重要提示： 不要运行 rails app:update，因为它会在不考虑本地自定义的情况下覆盖文件。相反，请遵循此选择性合并流程：

9.1：检测本地自定义

在进行任何升级之前，识别具有本地自定义的文件：

# 检查未提交的更改
git status

# 列出与全新 Rails 应用不同的配置文件
# 这些是我们需要谨慎处理的文件
git diff HEAD --name-only -- config/ bin/ public/

创建这些类别文件的心理清单：

自定义配置文件：具有项目特定设置的文件（i18n、邮件程序等）
修改过的 bin 脚本：具有自定义行为的脚本（使用 foreman 的 bin/dev 等）
标准文件：尚未自定义的文件

9.2：根据 Railsdiff 分析所需变更

根据步骤 6 中的 railsdiff 输出，对每个更改的文件进行分类：

类别	操作	示例
新文件	直接创建	`config/initializers/new_framework_defaults_X_Y.rb`
本地未更改	安全覆盖	`public/404.html`（如果未自定义）
本地已自定义	需要手动合并	`config/application.rb`、`bin/dev`
仅注释变更	通常跳过	配置文件中的次要注释更新

9.3：创建升级计划

向用户呈现清晰的升级计划：

## 升级计划：Rails X.Y.Z → A.B.C

### 新文件（将被创建）：
- config/initializers/new_framework_defaults_A_B.rb
- bin/ci（新的 CI 脚本）

### 安全更新（无本地自定义）：
- public/400.html
- public/404.html
- public/500.html

### 需要手动合并（检测到本地自定义）：
- config/application.rb
  └─ 本地：i18n 配置
  └─ Rails：[如有，描述新的 Rails 变更]

- config/environments/development.rb
  └─ 本地：letter_opener 邮件程序配置
  └─ Rails：[描述新的 Rails 变更]

- bin/dev
  └─ 本地：foreman + Procfile.dev 设置
  └─ Rails：更改为简单的 ruby 脚本

### 跳过（仅注释变更或不相关变更）：
- config/puma.rb（仅注释变更）

9.4：执行升级计划

用户确认计划后：

直接使用 railsdiff 中的内容或通过从全新的 Rails 应用中提取来创建它们：

# 生成一个临时的全新 Rails 应用以提取新文件
cd /tmp && rails new rails_template --skip-git --skip-bundle
# 然后复制所需的文件

或使用 Rails 生成器生成特定文件：

bin/rails app:update:configs  # 仅更新配置文件，仍然是交互式的

对于安全更新：

覆盖这些文件，因为它们没有本地自定义。

对于手动合并：

对于每个需要合并的文件，向用户展示：

当前本地版本（他们的自定义）
新的 Rails 默认值（来自 railsdiff）
建议的合并版本，该版本：
- 保留所有本地自定义
- 仅添加必要的新 Rails 功能
- 移除已弃用的设置

config/application.rb 的合并示例：

# 保留本地自定义：
config.i18n.available_locales = [:de, :en]
config.i18n.default_locale = :de
config.i18n.fallbacks = [:en]

# 添加新的 Rails 8.1 设置（如果需要）：
# （通常不需要 - 新的默认值通过 new_framework_defaults 文件引入）

9.5：处理 Active Storage 迁移

文件更新后，运行任何新的迁移：

bin/rails db:migrate

检查已添加的新迁移：

ls -la db/migrate/ | tail -10

启动 Rails 服务器并检查错误：
```
bin/dev  # 或 bin/rails server
```
检查 Rails 控制台：
```
bin/rails console
```
运行测试套件：
```
bin/rails test
```
查看日志中的弃用警告

步骤 10：最终确定框架默认值

验证应用程序正常工作后：

审查 config/initializers/new_framework_defaults_X_Y.rb
逐个启用每个新默认值，每次启用后进行测试
所有默认值都启用并测试后，更新 config/application.rb：
```
config.load_defaults X.Y  # 更新到新版本
```
删除 new_framework_defaults_X_Y.rb 文件

何时使用此技能

分析 Rails 应用并提供升级评估

在处理分析 Rails 应用并提供升级评估时使用此技能。

如果 gh CLI 未认证，请指导用户运行 gh auth login
如果 railsdiff.org 没有确切的版本，请尝试使用主版本.次版本.0 版本
如果应用程序已是最新版本，祝贺用户并注意任何即将发布的版本
如果本地自定义可能会丢失，务必在继续之前停止并向用户展示将被覆盖的内容

未经检查绝不覆盖 - 始终先检查本地自定义
保留用户意图 - 本地自定义的存在是有原因的
最小变更 - 仅添加新 Rails 版本必需的内容
透明度 - 在执行前向用户展示确切的变化
可逆性 - 用户应能通过 git checkout 恢复原状

🇺🇸English

When to Use This Skill

Analyze Rails apps and provide upgrade assessments

Use this skill when working with analyze rails apps and provide upgrade assessments.

Rails Upgrade Analyzer

Analyze the current Rails application and provide a comprehensive upgrade assessment with selective file merging.

Step 1: Verify Rails Application

Check that we're in a Rails application by looking for these files:

Gemfile (must exist and contain 'rails')
config/application.rb (Rails application config)
config/environment.rb (Rails environment)

If any of these are missing or don't indicate a Rails app, stop and inform the user this doesn't appear to be a Rails application.

Step 2: Get Current Rails Version

Extract the current Rails version from:

First, check Gemfile.lock for the exact installed version (look for rails (x.y.z))
If not found, check Gemfile for the version constraint

Report the exact current version (e.g., 7.1.3).

Step 3: Find Latest Rails Version

Use the GitHub CLI to fetch the latest Rails release:

gh api repos/rails/rails/releases/latest --jq '.tag_name'

This returns the latest stable version tag (e.g., v8.0.1). Strip the 'v' prefix for comparison.

Also check recent tags to understand the release landscape:

gh api repos/rails/rails/tags --jq '.[0:10] | .[].name'

Step 4: Determine Upgrade Type

Compare current and latest versions to classify the upgrade:

Patch upgrade : Same major.minor, different patch (e.g., 7.1.3 → 7.1.5)
Minor upgrade : Same major, different minor (e.g., 7.1.3 → 7.2.0)
Major upgrade : Different major version (e.g., 7.1.3 → 8.0.0)

Step 5: Fetch Upgrade Guide

Use WebFetch to get the official Rails upgrade guide:

URL: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html

Look for sections relevant to the version jump. The guide is organized by target version with sections like:

"Upgrading from Rails X.Y to Rails X.Z"
Breaking changes
Deprecation warnings
Configuration changes
Required migrations

Extract and summarize the relevant sections for the user's specific upgrade path.

Step 6: Fetch Rails Diff

Use WebFetch to get the diff between versions from railsdiff.org:

URL: https://railsdiff.org/{current_version}/{target_version}

For example: https://railsdiff.org/7.1.3/8.0.0

This shows:

Changes to default configuration files
New files that need to be added
Modified initializers
Updated dependencies
Changes to bin/ scripts

Summarize the key file changes.

Step 7: Check JavaScript Dependencies

Rails applications often include JavaScript packages that should be updated alongside Rails. Check for and report on these dependencies.

7.1: Identify JS Package Manager

Check which package manager the app uses:

# Check for package.json (npm/yarn)
ls package.json 2>/dev/null

# Check for importmap (Rails 7+)
ls config/importmap.rb 2>/dev/null

7.2: Check Rails-Related JS Packages

If package.json exists, check for these Rails-related packages:

# Extract current versions of Rails-related packages
cat package.json | grep -E '"@hotwired/|"@rails/|"stimulus"|"turbo-rails"' || echo "No Rails JS packages found"

Key packages to check:

Package	Purpose	Version Alignment
`@hotwired/turbo-rails`	Turbo Drive/Frames/Streams	Should match Rails version era
`@hotwired/stimulus`	Stimulus JS framework	Generally stable across Rails versions
`@rails/actioncable`	WebSocket support	Should match Rails version
`@rails/activestorage`	Direct uploads	Should match Rails version
`@rails/actiontext`

7.3: Check for Updates

For npm/yarn projects, check for available updates:

# Using npm
npm outdated @hotwired/turbo-rails @hotwired/stimulus @rails/actioncable @rails/activestorage 2>/dev/null

# Or check latest versions directly
npm view @hotwired/turbo-rails version 2>/dev/null
npm view @rails/actioncable version 2>/dev/null

7.4: Check Importmap Pins (if applicable)

If the app uses importmap-rails, check config/importmap.rb for pinned versions:

cat config/importmap.rb | grep -E 'pin.*turbo|pin.*stimulus|pin.*@rails' || echo "No importmap pins found"

To update importmap pins:

bin/importmap pin @hotwired/turbo-rails
bin/importmap pin @hotwired/stimulus

7.5: JS Dependency Summary

Include in the upgrade summary:

### JavaScript Dependencies

**Package Manager**: [npm/yarn/importmap/none]

| Package | Current | Latest | Action |
|---------|---------|--------|--------|
| @hotwired/turbo-rails | 8.0.4 | 8.0.12 | Update recommended |
| @rails/actioncable | 7.1.0 | 8.0.0 | Update with Rails |
| ... | ... | ... | ... |

**Recommended JS Updates:**
- Run `npm update @hotwired/turbo-rails` (or yarn equivalent)
- Run `npm update @rails/actioncable @rails/activestorage` to match Rails version

Step 8: Generate Upgrade Summary

Provide a comprehensive summary including all findings from Steps 1-7:

Version Information

Current version: X.Y.Z
Latest version: A.B.C
Upgrade type: [Patch/Minor/Major]

Upgrade Complexity Assessment

Rate the upgrade as Small , Medium , or Large based on:

Factor	Small	Medium	Large
Version jump	Patch only	Minor version	Major version
Breaking changes	None	Few, well-documented	Many, significant
Config changes	Minimal	Moderate	Extensive
Deprecations	None active	Some to address	Many requiring refactoring
Dependencies	Compatible	Some updates needed	Major dependency updates

Key Changes to Address

List the most important changes the user needs to handle:

Configuration file updates
Deprecated methods/features to update
New required dependencies
Database migrations needed
Breaking API changes

Recommended Upgrade Steps

Update test suite and ensure passing
Review deprecation warnings in current version
Update Gemfile with new Rails version
Run bundle update rails
Update JavaScript dependencies (see JS Dependencies section)
DO NOT runrails app:update directly - use the selective merge process below
Run database migrations
Run test suite
Review and update deprecated code

Resources

Rails Upgrade Guide: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html
Rails Diff: https://railsdiff.org/{current}/{target}
Release Notes: https://github.com/rails/rails/releases/tag/v{target}

When to Use This Skill

Analyze Rails apps and provide upgrade assessments

Use this skill when working with analyze rails apps and provide upgrade assessments.

Step 9: Selective File Update (replaces `rails app:update`)

IMPORTANT: Do NOT run rails app:update as it overwrites files without considering local customizations. Instead, follow this selective merge process:

9.1: Detect Local Customizations

Before any upgrade, identify files with local customizations:

# Check for uncommitted changes
git status

# List config files that differ from a fresh Rails app
# These are the files we need to be careful with
git diff HEAD --name-only -- config/ bin/ public/

Create a mental list of files in these categories:

Custom config files : Files with project-specific settings (i18n, mailer, etc.)
Modified bin scripts : Scripts with custom behavior (bin/dev with foreman, etc.)
Standard files : Files that haven't been customized

9.2: Analyze Required Changes from Railsdiff

Based on the railsdiff output from Step 6, categorize each changed file:

Category	Action	Example
New files	Create directly	`config/initializers/new_framework_defaults_X_Y.rb`
Unchanged locally	Safe to overwrite	`public/404.html` (if not customized)
Customized locally	Manual merge needed	`config/application.rb`, `bin/dev`
Comment-only changes	Usually skip	Minor comment updates in config files

9.3: Create Upgrade Plan

Present the user with a clear upgrade plan:

## Upgrade Plan: Rails X.Y.Z → A.B.C

### New Files (will be created):
- config/initializers/new_framework_defaults_A_B.rb
- bin/ci (new CI script)

### Safe to Update (no local customizations):
- public/400.html
- public/404.html
- public/500.html

### Needs Manual Merge (local customizations detected):
- config/application.rb
  └─ Local: i18n configuration
  └─ Rails: [describe new Rails changes if any]

- config/environments/development.rb
  └─ Local: letter_opener mailer config
  └─ Rails: [describe new Rails changes]

- bin/dev
  └─ Local: foreman + Procfile.dev setup
  └─ Rails: changed to simple ruby script

### Skip (comment-only or irrelevant changes):
- config/puma.rb (only comment changes)

9.4: Execute Upgrade Plan

After user confirms the plan:

For New Files:

Create them directly using the content from railsdiff or by extracting from a fresh Rails app:

# Generate a temporary fresh Rails app to extract new files
cd /tmp && rails new rails_template --skip-git --skip-bundle
# Then copy needed files

Or use the Rails generator for specific files:

bin/rails app:update:configs  # Only updates config files, still interactive

For Safe Updates:

Overwrite these files as they have no local customizations.

For Manual Merges:

For each file needing merge, show the user:

Current local version (their customizations)
New Rails default (from railsdiff)
Suggested merged version that:
- Keeps all local customizations
- Adds only essential new Rails functionality
- Removes deprecated settings

Example merge for config/application.rb:

# KEEP local customizations:
config.i18n.available_locales = [:de, :en]
config.i18n.default_locale = :de
config.i18n.fallbacks = [:en]

# ADD new Rails 8.1 settings if needed:
# (usually none required - new defaults come via new_framework_defaults file)

9.5: Handle Active Storage Migrations

After file updates, run any new migrations:

bin/rails db:migrate

Check for new migrations that were added:

ls -la db/migrate/ | tail -10

9.6: Verify Upgrade

After completing the merge:

Start the Rails server and check for errors:
```
bin/dev  # or bin/rails server
```
Check the Rails console:
```
bin/rails console
```
Run the test suite:
```
bin/rails test
```
Review deprecation warnings in logs

Step 10: Finalize Framework Defaults

After verifying the app works:

Review config/initializers/new_framework_defaults_X_Y.rb
Enable each new default one by one, testing after each
Once all defaults are enabled and tested, update config/application.rb:
```
config.load_defaults X.Y  # Update to new version
```
Delete the new_framework_defaults_X_Y.rb file

When to Use This Skill

Analyze Rails apps and provide upgrade assessments

Use this skill when working with analyze rails apps and provide upgrade assessments.

Error Handling

If gh CLI is not authenticated, instruct the user to run gh auth login
If railsdiff.org doesn't have the exact versions, try with major.minor.0 versions
If the app is already on the latest version, congratulate the user and note any upcoming releases
If local customizations would be lost, ALWAYS stop and show the user what would be overwritten before proceeding

Key Principles

Never overwrite without checking - Always check for local customizations first
Preserve user intent - Local customizations exist for a reason
Minimal changes - Only add what's necessary for the new Rails version
Transparency - Show the user exactly what will change before doing it
Reversibility - User should be able to git checkout to restore if needed

Weekly Installs

Repository

sickn33/antigra…e-skills

GitHub Stars

27.1K

First Seen

Feb 2, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode90

github-copilot89

codex89

kimi-cli87

gemini-cli87

amp87

Rails应用升级分析器 - 自动化评估与升级指南

🇨🇳中文介绍

何时使用此技能

Rails 升级分析器

步骤 1：验证 Rails 应用程序

步骤 2：获取当前 Rails 版本

相关 Skills

步骤 3：查找最新的 Rails 版本

步骤 4：确定升级类型

步骤 5：获取升级指南

步骤 6：获取 Rails 差异

步骤 7：检查 JavaScript 依赖项

7.1：识别 JS 包管理器

7.2：检查与 Rails 相关的 JS 包

7.3：检查更新

7.4：检查 Importmap 固定版本（如果适用）

7.5：JS 依赖项摘要

步骤 8：生成升级摘要

版本信息

升级复杂度评估

需要处理的关键变更

推荐的升级步骤

资源

何时使用此技能

步骤 9：选择性文件更新（替代 rails app:update）

9.1：检测本地自定义

9.2：根据 Railsdiff 分析所需变更

9.3：创建升级计划

9.4：执行升级计划

对于新文件：

对于安全更新：

对于手动合并：

9.5：处理 Active Storage 迁移

9.6：验证升级

步骤 10：最终确定框架默认值

何时使用此技能

错误处理

关键原则

🇺🇸English

When to Use This Skill

Rails Upgrade Analyzer

Step 1: Verify Rails Application

Step 2: Get Current Rails Version

Step 3: Find Latest Rails Version

Step 4: Determine Upgrade Type

Step 5: Fetch Upgrade Guide

Step 6: Fetch Rails Diff

Step 7: Check JavaScript Dependencies

7.1: Identify JS Package Manager

7.2: Check Rails-Related JS Packages

7.3: Check for Updates

7.4: Check Importmap Pins (if applicable)

7.5: JS Dependency Summary

Step 8: Generate Upgrade Summary

Version Information

Upgrade Complexity Assessment

Key Changes to Address

Recommended Upgrade Steps

Resources

When to Use This Skill

Step 9: Selective File Update (replaces rails app:update)

9.1: Detect Local Customizations

9.2: Analyze Required Changes from Railsdiff

9.3: Create Upgrade Plan

9.4: Execute Upgrade Plan

For New Files:

For Safe Updates:

For Manual Merges:

9.5: Handle Active Storage Migrations

9.6: Verify Upgrade

Step 10: Finalize Framework Defaults

When to Use This Skill

Error Handling

Key Principles

步骤 9：选择性文件更新（替代 `rails app:update`）

Step 9: Selective File Update (replaces `rails app:update`)