rails-upgrade

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：アップグレードの種類の判定

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

• パッチアップグレード：メジャーとマイナーが同じで、パッチが異なる場合（例：7.1.3 → 7.1.5）
• マイナーアップグレード：メジャーが同じで、マイナーが異なる場合（例：7.1.3 → 7.2.0）
• メジャーアップグレード：メジャーバージョンが異なる場合（例：7.1.3 → 8.0.0）

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

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

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

バージョンの差分に関連するセクションを確認します。ガイドは対象バージョンごとに構成されており、次のようなセクションがあります。

• 「Rails X.Y から Rails X.Z へのアップグレード」
• 破壊的変更
• 非推奨の警告
• 設定の変更
• 必須のマイグレーション

ユーザーの具体的なアップグレード経路に関連するセクションを抽出し、要約してください。

ステップ 6：Rails の差分の取得

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

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

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

次の内容が示されます。

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

主なファイル変更を要約してください。

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

Rails アプリケーションには、Rails とあわせて更新すべき JavaScript パッケージが含まれていることがよくあります。次の依存関係を確認し、報告してください。

7.1：JavaScript パッケージマネージャーの特定

アプリケーションで使用しているパッケージマネージャーを確認します。

# 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 関連の JavaScript パッケージの確認

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 JavaScript フレームワーク	通常、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：JavaScript 依存関係の概要

アップグレードの概要に次の内容を含めます。

### 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
• アップグレードの種類：[パッチ／マイナー／メジャー]

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

次の要素に基づいて、アップグレードを小規模、中規模、大規模のいずれかに評価します。

要素	小規模	中規模	大規模
バージョンの差	パッチのみ	マイナーバージョン	メジャーバージョン
破壊的変更	なし	少数で、十分に文書化されている	多数で、影響が大きい
設定の変更	最小限	中程度	広範囲
非推奨項目	現在有効なものはなし	対応が必要なものがいくつかある	リファクタリングが必要なものが多数ある
依存関係	互換性あり	一部の更新が必要	主要な依存関係の更新が必要

対応が必要な主な変更点

ユーザーが対応する必要がある最も重要な変更点を列挙します。

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 アップグレードガイド：https://guides.rubyonrails.org/upgrading_ruby_on_rails.html
• Rails Diff：https://railsdiff.org/{current}/{target}
• リリースノート：https://github.com/rails/rails/releases/tag/v{target}

---

ステップ 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：アップグレード計画を実行する

ユーザーが計画を確認した後、次の手順を実行します。

新規ファイルの場合：

raildiff の内容を使用するか、新しい 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 のデフォルト（raildiff から取得）
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. 新しいデフォルト設定を一つずつ有効にし、その都度テストします
3. すべてのデフォルト設定を有効にしてテストしたら、config/application.rb を更新します：

   config.load_defaults X.Y  # Update to new version
   

4. new_framework_defaults_X_Y.rb ファイルを削除します

---

エラー処理

• gh CLI が認証されていない場合は、gh auth login を実行するようユーザーに指示します
• railsdiff.org に完全に一致するバージョンがない場合は、major.minor.0 バージョンを試します
• アプリがすでに最新バージョンの場合は、ユーザーを祝福し、今後のリリースについて伝えます
• ローカルのカスタマイズが失われる可能性がある場合は、続行する前に必ず処理を中止し、上書きされる内容をユーザーに示します

重要な原則

1. 確認せずに上書きしない - まずローカルのカスタマイズがないか必ず確認します
2. ユーザーの意図を尊重する - ローカルのカスタマイズには存在する理由があります
3. 変更を最小限にする - 新しい Rails バージョンに必要なものだけを追加します
4. 透明性を確保する - 変更を行う前に、何が変わるのかをユーザーに正確に示します
5. 元に戻せるようにする - 必要に応じてユーザーが git checkout で復元できるようにします