skill-rails-upgrade

Rails Upgrade Analyzer - 智能 Rails 升级评估助手

技能概述

Rails Upgrade Analyzer 是一个专门用于分析 Ruby on Rails 应用并生成全面升级评估报告的智能助手。它能自动检测当前 Rails 版本，获取最新版本信息，并提供选择性文件合并方案，帮助你安全、可控地完成框架升级。

适用场景

1. 版本升级前的全面评估

在升级 Rails 之前，了解当前版本与目标版本的差异至关重要。该技能会分析你的 Gemfile.lock 和 Gemfile，提取精确的当前版本，获取最新稳定版本，并分类升级类型（补丁升级、次要版本升级或主版本升级）。它还会从官方 Rails 升级指南和 railsdiff.org 获取相关变更信息，为你提供完整的升级复杂度评估。

2. 保护本地配置的选择性升级

传统的 rails app:update 命令会直接覆盖配置文件，可能导致你的本地定制配置丢失。Rails Upgrade Analyzer 采用智能合并策略：首先检测你的本地定制文件（如 i18n 配置、邮件设置、自定义启动脚本等），然后根据 railsdiff 分析每个变更文件的影响，分类为"新文件"、"安全覆盖"、"需手动合并"或"可跳过"，确保不会意外覆盖你的重要配置。

3. 依赖生态的完整检查

Rails 升级不仅涉及框架本身，还包括 JavaScript 依赖和数据库迁移。该技能会检查你的项目使用的包管理器（npm/yarn/importmap），识别与 Rails 相关的 JavaScript 包（如 @hotwired/turbo-rails、@rails/actioncable 等），并提供版本对齐建议。它还会提醒你运行新的数据库迁移，并在升级后提供完整的验证清单。

核心功能

1. 版本差异分析

通过 GitHub CLI 自动获取 Rails 最新发布版本，与你的当前版本进行对比，确定升级类型。同时抓取官方 Rails 升级指南和 railsdiff.org 的变更详情，提取与你升级路径相关的破坏性变更、弃用警告、配置变更和必需的迁移操作。

2. 选择性文件合并

替代 rails app:update 的覆盖式更新，采用智能合并流程。首先通过 git 状态检测本地定制文件，然后根据 railsdiff 分析每个文件的变更类型。对于需要手动合并的文件，会提供清晰的对比：保留你的本地定制，仅添加必要的新 Rails 功能，并移除已弃用的设置。

3. 升级复杂度评估

基于版本跨度、破坏性变更数量、配置变更程度、弃用处理需求和依赖更新范围，将升级评定为"小型"、"中型"或"大型"，并提供相应的升级步骤建议和注意事项。

常见问题

如何安全地升级 Rails 版本？

Rails Upgrade Analyzer 建议的升级流程：首先确保测试套件通过并审查当前版本的弃用警告；然后更新 Gemfile 并运行 bundle update rails；更新 JavaScript 依赖；使用本技能的选择性合并流程而非直接运行 rails app:update；运行数据库迁移；最后运行测试套件并审查弃用代码。整个过程保持 git 可追溯性，任何步骤都可以回滚。

Rails 升级会覆盖我的配置文件吗？

传统的 rails app:update 确实会覆盖配置文件，但本技能采用保护性策略。它会先检测你的本地定制（如 i18n 配置、邮件程序设置、自定义 bin 脚本等），然后分类处理：新文件直接创建，未修改的标准文件可以安全覆盖，有本地定制的文件则手动合并，仅添加必要的新功能并保留你的所有定制。升级前会向你展示完整的变更计划，确认后才执行。

Rails 从 7 升级到 8 需要注意什么？

主版本升级通常涉及更多破坏性变更。Rails Upgrade Analyzer 会自动抓取 Rails 8 的升级指南，提取关键变更点，如新的框架默认值、配置文件格式变化、已移除的方法和新增的必需依赖。对于 Rails 7 到 8 的升级，特别需要注意 JavaScript 生态的变化（如 Turbo、Stimulus 版本对齐）、Active Record 的 API 变更，以及可能需要调整的测试代码。技能会提供详细的变更清单和逐步验证指南。