skill-rails-upgrade

何时使用此技能

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

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

Rails 升级分析器

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

默认情况下，评估为只读。依赖项变更、生成的文件、迁移和应用启动，均需在用户要求的实施范围内进行。运行应用命令前，请确认数据库和环境；执行迁移时，请使用一次性开发数据库，并确保已测试恢复流程。

第 1 步：验证 Rails 应用

检查以下文件，确认当前目录是 Rails 应用：

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

如果缺少其中任何文件，或这些文件无法证明这是 Rails 应用，请停止并告知用户，这看起来并不是 Rails 应用。

第 2 步：获取当前 Rails 版本

按以下顺序提取当前 Rails 版本：

1. 首先检查 Gemfile.lock 中的确切安装版本（查找 rails (x.y.z)）
2. 如果没有找到，再检查 Gemfile 中的版本约束

报告确切的当前版本（例如 7.1.3）。

第 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 包管理器

检查应用使用的包管理器：

# 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：检查 Rails 相关 JS 包

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

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

需要检查的关键包：

包	用途	版本对应关系
@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 的版本时期相符

7.3：检查更新

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

# 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：检查 Importmap Pin（如适用）

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

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

更新 Importmap Pin：

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

7.5：JS 依赖摘要

将以下内容纳入升级摘要：

### 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

---

步骤 8：生成升级摘要

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

版本信息

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

升级复杂度评估

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

因素	小型	中型	大型
版本跨度	仅补丁版本	次要版本	主要版本
破坏性变更	无	少量，且有完善文档	多且影响显著
配置变更	极少	中等	大量
弃用项	无正在使用的弃用项	有一些需要处理	有许多需要重构的项
依赖项	兼容	需要更新一些	需要更新主要依赖项

需要处理的关键变更

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

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

建议的升级步骤

1. 更新测试套件并确保测试通过
2. 查看当前版本中的弃用警告
3. 使用新的 Rails 版本更新 Gemfile
4. 运行 bundle update rails
5. 更新 JavaScript 依赖项（参见“JS 依赖项”部分）
6. 不要直接运行 rails app:update——请使用下方的选择性合并流程
7. 运行数据库迁移
8. 运行测试套件
9. 查看并更新弃用代码

资源

• Rails 升级指南：https://guides.rubyonrails.org/upgrading_ruby_on_rails.html
• Rails 差异：https://railsdiff.org/{current}/{target}
• 发布说明：https://github.com/rails/rails/releases/tag/v{target}

---

何时使用此技能

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

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

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

如果本地自定义内容很重要，优先采用经过审查的选择性合并。rails app:update 可能会提示处理冲突，但不能替代对生成差异的审查。切勿假设生成的默认内容可以安全覆盖现有内容。

9.1：检测本地自定义内容

任何升级之前，先找出包含本地自定义内容的文件：

# Check for uncommitted changes
git status

# This lists only uncommitted differences, NOT all customization from Rails defaults.
# Compare the complete tracked files against a clean app generated with the
# exact current Rails version/options before declaring a file uncustomized.
git diff HEAD --name-only -- config/ bin/ public/

在以下类别中列出相关文件：

• 自定义配置文件：包含项目专属设置的文件（i18n、mailer 等）
• 已修改的 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：制定升级计划

向用户提供清晰的升级计划：

## 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：执行升级计划

用户确认计划后：

对于新文件：

使用 railsdiff 中的内容直接创建，或从全新的 Rails 应用中提取内容：

# Generate a temporary fresh Rails app to extract new files
# Use a fresh unique temporary directory and the exact target Rails version.
# Inspect generator side effects/options before running; do not reuse /tmp paths.
# Then copy needed files

也可以使用 Rails 生成器创建特定文件：

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

对于可安全更新的文件：

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

对于手动合并：

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

1. 当前本地版本（用户的自定义内容）
2. 新的 Rails 默认内容（来自 railsdiff）
3. 建议的合并版本，该版本：
   • 保留所有本地自定义内容
   • 仅添加必要的新 Rails 功能
   • 移除已弃用的设置

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：处理 Active Storage 迁移

更新文件后，运行所有新增迁移：

bin/rails db:migrate

检查是否添加了新迁移：

ls -la db/migrate/ | tail -10

9.6：验证升级

完成合并后：

1. 启动 Rails 服务器并检查是否有错误：

   bin/dev  # or bin/rails server
   

2. 检查 Rails 控制台：

   bin/rails console
   

3. 运行测试套件：

   bin/rails test
   

4. 查看日志中的弃用警告

---

第 10 步：完成框架默认设置

确认应用正常运行后：

1. 检查 config/initializers/new_framework_defaults_X_Y.rb
2. 逐一启用每项新默认设置，并在每次启用后进行测试
3. 启用并测试所有默认设置后，更新 config/application.rb：

   config.load_defaults X.Y  # Update to new version
   

4. 删除 new_framework_defaults_X_Y.rb 文件

---

何时使用此技能

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

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

错误处理

• 如果 gh CLI 未通过身份验证，请指示用户运行 gh auth login
• 如果 railsdiff.org 没有完全匹配的版本，请尝试使用 major.minor.0 版本
• 如果应用已使用最新版本，请祝贺用户并说明即将发布的版本
• 如果本地自定义内容可能丢失，务必停止操作，并在继续前向用户展示将被覆盖的内容

核心原则

1. 未经检查，绝不覆盖——始终先检查本地自定义内容
2. 尊重用户意图——本地自定义内容都有其原因
3. 尽量少改动——仅添加新 Rails 版本所必需的内容
4. 透明——在操作前向用户准确说明将发生的更改
5. 恢复——单独保留源代码更改；Git 无法撤销数据库迁移、远程操作或生成的数据。请使用经过测试的数据库恢复方案。

限制

• 仅在任务明确符合上述范围时使用此技能。
• 不要将输出视为特定环境验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。