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／6.x をテストせずに >= 5.2 とするなど）は、気づきにくい非互換性を招きます。
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. オプションの統合（ジョブ、メーラー、アセット、ルート、インストールジェネレーター、ダミーアプリのマウント）をバージョンごとに確認します。統合機能が存在しない場合も、その確認内容を明記します。
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. jobs、mailers、assets、routes、generators、dummy app mount の行を含むオプション統合マトリクスを記載します。各行には present/absent、確認したファイルパス、バージョンごとの検証コマンドを記載します。
6. 言語 — 明示的に別途指定されない限り、英語を使用する必要があります。

統合

スキル	連携するタイミング
test-engine	テストマトリクスの設定、CI 構成、複数バージョンのテスト
create-engine	エンジンの構造、ホストとの契約、名前空間の設計
release-engine	バージョン管理、変更履歴、互換性変更に関するアップグレードノート