依存関係を安全にアップグレードする
目標：1つの依存関係（または密結合されたグループ）を、破壊的変更が後から発覚するのではなく、事前に理解した状態で新しいバージョンに移行すること。
計画
- 現在の状態を確定する。 インストールされているバージョン（マニフェストだけでなくロックファイルから）とターゲットバージョンを特定する。ユーザーが「最新」と言った場合は、パッケージマネージャー（
npm view <pkg> version、pip index versions <pkg>、cargo searchなど）で調べて、そのバージョン番号を明示する。 - ベースラインを記録する クリーンなワーキングツリー上で：インストール、ビルド、テスト、リント、型チェック。アップグレードのせいにしないために、既存の失敗があれば記録しておく。
- 実際のリリースノートを読む。 現在のバージョンとターゲットバージョンの間のすべてのバージョンについて、チェンジログ、リリースノート、またはマイグレーションガイドを開く。以下を抽出する：破壊的変更、削除またはリネームされたAPI、新しい最小ランタイムバージョン、変更されたデフォルト値、非推奨項目。各項目についてソースリンクを引用する。リリースノートが見つからない場合はその旨を述べ、アップグレードのリスクが高いものとして扱う。
- 影響をマッピングする。
rgを使用してコードベース内で削除、リネーム、または変更された各APIを検索する。編集前に影響を受けるファイルをリストアップする。
実行
- この依存関係（および必要なピア依存関係）のみをアップグレードする。包括的な「すべて更新」は実行しない。
- マニフェストとロックファイルは手動ではなく、プロジェクトのパッケージマネージャーで更新する。
- リリースノートが必要とするコード変更を、小さいものから順に行う。新しい形式が同等である場合は、非推奨の使用箇所を置き換える。
- インストール、ビルド、テスト、リント、型チェックを再度実行する。ベースラインと比較する。
- メジャーバージョンの場合は、可能であればアプリケーションまたは主要なサンプルパスも実行し、バンドルサイズ、起動時の警告、非推奨警告を確認する。
- アップグレードに最小ランタイムまたはピアバージョンのバンプが必要な場合は、変更する前に止めて確認を求める。
レポート
アップグレード: <pkg> <from> -> <to>
ソース: <changelog links>
適用された破壊的変更: <list with file refs>
行った変更: <summary>
検証: <commands, baseline vs after>
警告またはフォローアップ: <deprecations, skipped items, risks>
ロールバック: revert <files>, または `git revert <commit>`
ルール
- アップグレードとリファクタリングを同じ変更で決して行わない。
- 失敗するテストをスキップしたり、問題を隠すためにバージョン範囲を緩めたりしない。
- セキュリティ修正：アップグレードが対処するアドバイザリについて、公式アドバイザリまたはリリースノートで確認した場合のみ記載する。
- 推移的な依存関係が競合を引き起こす場合は、競合の出力を表示し、盲目的に上書きするのではなく、選択肢を提案する。