skill-rails-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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应用并提供升级评估

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

Rails Upgrade Analyzer

Rails升级分析工具

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

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

Step 1: Verify Rails Application

步骤1：验证Rails应用

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.

通过检查以下文件确认当前处于Rails应用环境中：

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

如果缺少其中任何一个文件，或文件无法表明这是Rails应用，请停止操作并告知用户这似乎不是一个Rails应用。

Step 2: Get Current Rails Version

步骤2：获取当前Rails版本

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

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

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

报告精确的当前版本（例如：

7.1.3

）。

Step 3: Find Latest Rails Version

步骤3：查找最新Rails版本

Use the GitHub CLI to fetch the latest Rails release:

bash

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:

bash

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

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

bash

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

该命令会返回最新稳定版本标签（例如：

v8.0.1

）。去掉前缀'v'后用于版本对比。

同时检查近期标签以了解版本发布情况：

bash

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

Step 4: Determine Upgrade Type

步骤4：确定升级类型

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)

对比当前版本与最新版本，对升级类型进行分类：

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

Step 5: Fetch Upgrade Guide

步骤5：获取升级指南

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.

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

URL:

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

查找与版本跨度相关的章节。指南按目标版本组织，包含以下类型的章节：

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

提取并总结与用户具体升级路径相关的内容。

Step 6: Fetch Rails Diff

步骤6：获取Rails版本差异

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.

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

URL:

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

示例：

https://railsdiff.org/7.1.3/8.0.0

该页面会展示：

默认配置文件的变更
需要新增的文件
修改后的初始化文件
更新的依赖项
bin/目录下脚本的变更

总结关键的文件变更内容。

Step 7: Check JavaScript Dependencies

步骤7：检查JavaScript依赖项

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

Rails应用通常包含需要与Rails同步更新的JavaScript包。检查并报告这些依赖项的情况。

7.1: Identify JS Package Manager

7.1：识别JS包管理器

Check which package manager the app uses:

bash

undefined

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

bash

undefined

Check for package.json (npm/yarn)

检查package.json（npm/yarn）

ls package.json 2>/dev/null

Check for importmap (Rails 7+)

检查importmap（Rails 7+）

ls config/importmap.rb 2>/dev/null

undefined

ls config/importmap.rb 2>/dev/null

undefined

7.2: Check Rails-Related JS Packages

7.2：检查与Rails相关的JS包

package.json

exists, check for these Rails-related packages:

bash

undefined

如果

package.json

存在，检查以下与Rails相关的包：

bash

undefined

Extract current versions of Rails-related packages

提取与Rails相关包的当前版本

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` | Rich text editing | Should match Rails version |
| `@rails/request.js` | Rails UJS replacement | Should match Rails version era |

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版本时代匹配 |

7.3: Check for Updates

7.3：检查更新

For npm/yarn projects, check for available updates:

bash

undefined

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

bash

undefined

Using npm

使用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

undefined

npm view @hotwired/turbo-rails version 2>/dev/null npm view @rails/actioncable version 2>/dev/null

undefined

7.4: Check Importmap Pins (if applicable)

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

If the app uses importmap-rails, check

config/importmap.rb

for pinned versions:

bash

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

To update importmap pins:

bash

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

如果应用使用importmap-rails，检查

config/importmap.rb

中的固定版本：

bash

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

更新importmap固定版本的命令：

bash

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

7.5: JS Dependency Summary

7.5：JS依赖项总结

Include in the upgrade summary:

undefined

在升级总结中包含以下内容：

undefined

JavaScript Dependencies

JavaScript依赖项

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

---

包管理器: [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版本

---

Step 8: Generate Upgrade Summary

步骤8：生成升级总结

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

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

Version Information

版本信息

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

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

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

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

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

Recommended Upgrade Steps

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}

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}

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应用并提供升级评估

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

Step 9: Selective File Update (replaces

rails app:update

)

步骤9：选择性文件更新（替代

rails app:update

）

IMPORTANT: Do NOT run

rails app:update

as it overwrites files without considering local customizations. Instead, follow this selective merge process:

重要提示： 请勿运行

rails app:update

，因为它会无视本地自定义内容直接覆盖文件。请遵循以下选择性合并流程：

9.1: Detect Local Customizations

9.1：检测本地自定义内容

Before any upgrade, identify files with local customizations:

bash

undefined

在进行任何升级前，识别包含本地自定义内容的文件：

bash

undefined

Check for uncommitted changes

检查未提交的变更

git status

List config files that differ from a fresh Rails app

列出与全新Rails应用存在差异的配置文件

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

git diff HEAD --name-only -- config/ bin/ public/


创建以下类别的文件清单：
- **自定义配置文件**：包含项目特定设置的文件（如i18n、邮件器配置等）
- **修改后的bin脚本**：包含自定义行为的脚本（如带有foreman的bin/dev等）
- **标准文件**：未被自定义的文件

9.2: Analyze Required Changes from Railsdiff

9.2：分析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

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

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

9.3: Create Upgrade Plan

9.3：创建升级计划

Present the user with a clear upgrade plan:

undefined

向用户展示清晰的升级计划：

undefined

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

升级计划：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)

config/initializers/new_framework_defaults_A_B.rb
bin/ci（新的CI脚本）

Safe to Update (no local customizations):

可安全更新的文件（无本地自定义）：

public/400.html
public/404.html
public/500.html

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

config/application.rb └─ 本地自定义：i18n配置 └─ Rails变更：[描述Rails的新变更（如有）]
config/environments/development.rb └─ 本地自定义：letter_opener邮件器配置 └─ Rails变更：[描述Rails的新变更]
bin/dev └─ 本地自定义：foreman + Procfile.dev配置 └─ Rails变更：改为简单的Ruby脚本

Skip (comment-only or irrelevant changes):

可跳过的文件（仅注释变更或无关变更）：

config/puma.rb (only comment changes)

undefined

config/puma.rb（仅注释变更）

undefined

9.4: Execute Upgrade Plan

9.4：执行升级计划

After user confirms the plan:

用户确认计划后执行：

For New Files:

对于新文件：

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

bash

undefined

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

bash

undefined

Generate a temporary fresh Rails app to extract new files

生成临时的全新Rails应用以提取新文件

cd /tmp && rails new rails_template --skip-git --skip-bundle

Then copy needed files

然后复制需要的文件


Or use the Rails generator for specific files:
```bash
bin/rails app:update:configs  # Only updates config files, still interactive


或使用Rails生成器创建特定文件：
```bash
bin/rails app:update:configs  # 仅更新配置文件，仍为交互式操作

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

ruby

undefined

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

当前本地版本（用户的自定义内容）
新的Rails默认版本（来自railsdiff）
建议的合并版本，需满足：
- 保留所有本地自定义内容
- 仅添加新Rails版本必需的功能
- 移除已弃用的设置

config/application.rb

的合并示例：

ruby

undefined

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:

如有需要，添加Rails 8.1的新设置:

(usually none required - new defaults come via new_framework_defaults file)

（通常不需要 - 新默认值通过new_framework_defaults文件生效）

undefined

undefined

9.5: Handle Active Storage Migrations

9.5：处理Active Storage迁移

After file updates, run any new migrations:

bash

bin/rails db:migrate

Check for new migrations that were added:

bash

ls -la db/migrate/ | tail -10

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

bash

bin/rails db:migrate

检查新增的迁移文件：

bash

ls -la db/migrate/ | tail -10

9.6: Verify Upgrade

9.6：验证升级结果

After completing the merge:

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

完成合并后验证应用是否正常运行：

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

Step 10: Finalize Framework Defaults

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

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

ruby

config.load_defaults X.Y  # Update to new version

Delete the
```
new_framework_defaults_X_Y.rb
```
file

验证应用正常运行后：

查看

config/initializers/new_framework_defaults_X_Y.rb

逐个启用每个新默认值，每次启用后进行测试

所有默认值启用并测试通过后，更新

config/application.rb

：

ruby

config.load_defaults X.Y  # 更新为新版本

删除
```
new_framework_defaults_X_Y.rb
```
文件

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应用并提供升级评估

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

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

如果
```
gh
```
CLI未认证，指导用户运行
```
gh auth login
```
如果railsdiff.org没有对应精确版本，尝试使用主版本.次版本.0的版本组合
如果应用已处于最新版本，恭喜用户并告知即将发布的版本信息
如果本地自定义内容会被覆盖，必须先停止操作并向用户展示会被覆盖的内容，再继续

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

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

skill-rails-upgrade

Original

Translation

When to Use This Skill

何时使用此技能

Rails Upgrade Analyzer

Rails升级分析工具

Step 1: Verify Rails Application

步骤1：验证Rails应用

Step 2: Get Current Rails Version

步骤2：获取当前Rails版本

Step 3: Find Latest Rails Version

步骤3：查找最新Rails版本

Step 4: Determine Upgrade Type

步骤4：确定升级类型

Step 5: Fetch Upgrade Guide

步骤5：获取升级指南

Step 6: Fetch Rails Diff

步骤6：获取Rails版本差异

Step 7: Check JavaScript Dependencies

步骤7：检查JavaScript依赖项

7.1: Identify JS Package Manager

7.1：识别JS包管理器

Check for package.json (npm/yarn)

检查package.json（npm/yarn）

Check for importmap (Rails 7+)

检查importmap（Rails 7+）

7.2: Check Rails-Related JS Packages

7.2：检查与Rails相关的JS包

Extract current versions of Rails-related packages

提取与Rails相关包的当前版本

7.3: Check for Updates

7.3：检查更新

Using npm

使用npm

Or check latest versions directly

或直接检查最新版本

7.4: Check Importmap Pins (if applicable)

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

7.5: JS Dependency Summary

7.5：JS依赖项总结

JavaScript Dependencies

JavaScript依赖项

Step 8: Generate Upgrade Summary

步骤8：生成升级总结

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：选择性文件更新（替代rails app:update）

9.1: Detect Local Customizations

9.1：检测本地自定义内容

Check for uncommitted changes

检查未提交的变更

List config files that differ from a fresh Rails app

列出与全新Rails应用存在差异的配置文件

These are the files we need to be careful with

这些是我们需要谨慎处理的文件

9.2: Analyze Required Changes from Railsdiff

9.2：分析Railsdiff中的必需变更

9.3: Create Upgrade Plan

9.3：创建升级计划

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

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

New Files (will be created):

需创建的新文件：

Safe to Update (no local customizations):

可安全更新的文件（无本地自定义）：

Needs Manual Merge (local customizations detected):

需要手动合并的文件（检测到本地自定义）：

Skip (comment-only or irrelevant changes):

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

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