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: アップグレードタイプの判定

現在のバージョンと最新バージョンを比較して、アップグレードを分類します:

• パッチアップグレード: 同じ major.minor、異なるパッチ (例: 7.1.3 → 7.1.5)
• マイナーアップグレード: 同じ major、異なる minor (例: 7.1.3 → 7.2.0)
• メジャーアップグレード: 異なる major バージョン (例: 7.1.3 → 8.0.0)

ステップ 5: アップグレードガイドの取得

WebFetch を使用して公式の Rails アップグレードガイドを取得します:

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

バージョンの飛躍に関連するセクションを探します。このガイドは対象バージョンごとに整理されており、以下のようなセクションがあります:

• 「Upgrading from Rails X.Y to Rails X.Z」
• 破壊的変更
• 非推奨の警告
• 設定の変更
• 必要なマイグレーション

ユーザー固有のアップグレードパスに関連するセクションを抽出して要約します。

ステップ 6: Rails Diff の取得

WebFetch を使用して railsdiff.org からバージョン間の差分を取得します:

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

例: https://railsdiff.org/7.1.3/8.0.0

これは以下を示します:

• デフォルト設定ファイルへの変更
• 追加が必要な新しいファイル
• 変更されたイニシャライザ
• 更新された依存関係
• bin/ スクリプトへの変更

主要なファイル変更を要約します。

ステップ 7: JavaScript 依存関係の確認

Rails アプリケーションにはしばしば JavaScript パッケージが含まれており、Rails と合わせて更新する必要があります。これらの依存関係を確認して報告します。

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 ピンの確認 (該当する場合)

アプリが importmap-rails を使用している場合、config/importmap.rb でピン留めされたバージョンを確認します:

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

importmap のピンを更新するには:

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
• アップグレードタイプ: [パッチ/マイナー/メジャー]

アップグレードの複雑さの評価

アップグレードを Small、Medium、Large のいずれかとして評価します。基準は次のとおりです:

要因	Small	Medium	Large
バージョンの飛躍	パッチのみ	マイナーバージョン	メジャーバージョン
破壊的変更	なし	少数で、十分に文書化されている	多数で、重大
設定変更	最小限	中程度	広範囲
非推奨	有効なものなし	対応すべきものがいくつか	リファクタリングが必要なものが多数
依存関係	互換性あり	いくつかの更新が必要	主要な依存関係の更新

対応すべき主な変更

ユーザーが処理する必要がある最も重要な変更を列挙します:

1. 設定ファイルの更新
2. 更新すべき非推奨のメソッド/機能
3. 新たに必要な依存関係
4. 必要なデータベースマイグレーション
5. 破壊的な API 変更

推奨されるアップグレード手順

1. テストスイートを更新し、合格することを確認する
2. 現在のバージョンにおける非推奨の警告を確認する
3. 新しい Rails バージョンで Gemfile を更新する
4. bundle update rails を実行する
5. JavaScript の依存関係を更新する(JS Dependencies セクションを参照)
6. rails app:update を直接実行しないでください - 以下の選択的マージプロセスを使用します
7. データベースマイグレーションを実行する
8. テストスイートを実行する
9. 非推奨のコードを確認して更新する

リソース

• 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 アプリを分析し、アップグレードの評価を提供します

Rails アプリを分析してアップグレードの評価を提供する作業を行うときに、このスキルを使用します。

ステップ 9: 選択的なファイル更新(rails app:update の代替)

重要: rails app:update はローカルのカスタマイズを考慮せずにファイルを上書きするため、実行しないでください。代わりに、以下の選択的マージプロセスに従ってください:

9.1: ローカルのカスタマイズを検出する

アップグレードの前に、ローカルのカスタマイズがあるファイルを特定します:

# Check for uncommitted changes
git status

# List config files that differ from a fresh Rails app
# These are the files we need to be careful with
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
cd /tmp && rails new rails_template --skip-git --skip-bundle
# 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. 新しいデフォルト設定を 1 つずつ有効化し、それぞれの後にテストします
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 checkout で復元できるようにします

制限事項

• このスキルは、タスクが上記の範囲に明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代替物として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が欠けている場合は、停止して確認を求めてください。