upgrade-engine

升级引擎

核心原则： 每个声明支持的 Rails/Ruby 版本都必须纳入 CI 矩阵。优先明确指定支持目标，而不是依赖意外兼容性。

硬性门槛

Before claiming support for a Rails/Ruby version:
  1. bundle exec rake zeitwerk:check        # verify autoloading on each version
  2. bundle exec rspec                       # full suite per matrix version
  3. CI matrix must pass — not just main Rails version

DO NOT ship compatibility changes without verifying both autoloading and full suite.

核心流程

1. 定义支持的 Ruby 和 Rails 版本——在 gemspec 和 README 中注明。
2. 运行 bundle exec rake zeitwerk:check——文件路径必须与常量名称完全匹配（例如，my_engine/widget_policy.rb → MyEngine::WidgetPolicy）。
3. 检查初始化器在启动和重新加载时的行为——对重新加载敏感的钩子使用 config.to_prepare；在加载时执行的钩子在开发环境中无法安全应对重新加载。
4. 验证 gemspec 依赖范围与测试版本一致：spec.add_dependency "rails", ">= 7.0", "< 8.0"——范围必须反映 CI 实际测试的内容。未设上限或过度声称兼容性（例如声明 >= 5.2，却未测试 5.2/6.x）会导致不易察觉的不兼容。
5. 用功能检测替代 Rails.version 分支——版本检查在不同补丁版本间很脆弱：

# ❌ Bad — brittle, wrong for patch versions
if Rails.version >= "7.0"
  config.active_support.cache_format_version = 7.0
end

# ✅ Good — detect the capability directly
if ActiveSupport::Cache.respond_to?(:format_version=)
  config.active_support.cache_format_version = 7.0
end

6. 按版本检查可选集成（作业、邮件程序、资源、路由、安装生成器、dummy 应用挂载）。即使某项集成不存在，也要注明检查情况。
7. CI 矩阵必须针对每种声明支持的 Rails/Ruby 组合运行：

strategy:
  matrix:
    include:
      - { ruby: "3.2", rails: "7.1" }
      - { ruby: "3.3", rails: "7.2" }

扩展资源

• assets/compatibility_matrix.md
• assets/zeitwerk_notes.md
• EXAMPLES.md

输出风格

1. 说明目标支持矩阵。
2. 列出最可能出现问题的环节。
3. 在隔离且可测试的边界中进行兼容性更改。
4. 如果尚无矩阵覆盖，建议添加。
5. 包含一个可选集成矩阵，列出作业、邮件程序、资源、路由、生成器和 dummy 应用挂载。每行注明 present/absent、检查的文件路径，以及逐版本验证命令。
6. 语言——除非明确要求其他语言，否则必须使用英语。

集成

Skill	何时串联
test-engine	测试矩阵设置、CI 配置、多版本测试
create-engine	引擎结构、宿主约定、命名空间设计
release-engine	版本管理、更新日志、兼容性更改说明