library-update-review

ライブラリ更新のレビュー手順書

ライブラリを更新する変更をレビューし、必要に応じてバージョン間のmigrationや、breaking changeへの対応も行う為の手順を説明します。

対象

• dependabotやrenovatebotが作成したライブラリ更新pull request
• 人間が作成したライブラリ更新pull request

章立てと実行すべき作業

以下に示した形式に従って章立てし、レポートを作成してください。 外部のドキュメントを参照した場合はそのURLを明記してください。

1. ライブラリの概要

ライブラリの概要を調査してください。 ライブラリ内READMEや公式サイトのドキュメントを確認して、何を実現するために、どのような用途で使われるライブラリなのかを報告してください。

2. バージョン情報

package.jsonを読んで、このpull requestによって変更される前と後のバージョン情報と、それぞれのリリース日時を報告してください。

npmjs.comやgithubを調査し、major versionの更新の有無を報告してください。 このpull requestではpatch versionやminor versionを更新しているが、実はそれが最新版ではなく、major versionの更新があるかもしれません。 major version更新ではライブラリの名前が変更されたり、リポジトリがorganizationに移管されたりする事があります。

3. ライブラリの依存関係

ライブラリの依存関係を確認してください。 package-lock.jsonを読んで依存関係を確認してください。grep -C15 ライブラリ名 package-lock.json のようなコマンドが有効です。

• そのライブラリに依存している他のライブラリがあれば列挙する
• そのライブラリが依存している他のライブラリがあれば列挙する

4. ライブラリの使用箇所とバージョン情報

リポジトリ内で、そのライブラリや実行環境が参照・指定されている箇所を調査してください。

import文やrequire文だけでなく、設定ファイル・Dockerfile・CI設定・開発環境設定など、バージョンが指定されている箇所も調査対象に含めてください。 git grep ライブラリ名 に加えて、バージョン番号やパッケージ名での検索も行ってください。

調査結果は、参照箇所をファイル単位で一覧にまとめてください。このリストはセクション6-2「バージョン整合性の確認」の入力として使います。 セクション3等の他セクションで読んだファイルにもバージョン指定が含まれている場合があるので、漏らさずリストに含めてください。

5. 変更内容の要約

変更内容を要約してください。 ライブラリの公式サイトやGithubを参照し、release noteやchangelog、migration guideを詳しく読んで変更内容を把握してください。 機能追加やAPIの仕様変更のうち、特にアプリケーション側で使っている機能に関係がありそうな変更を抜き出して、報告してください。 変更前と後の間に含まれる、全バージョンの変更内容を1つずつ確認する必要があります。

重要：pull requestの概要欄に書かれている説明は誤っている可能性があるので、無視してください。現状のコードとdiffだけを参考にしてください。

6. コード・設定の更新

ライブラリや実行環境の更新に伴い、アプリケーションコード・設定ファイルの修正が必要か確認してください。 必要に応じてpull requestの作成を提案してください。

以下の2つの観点を区別して確認してください。

6-1. APIや仕様変更に伴うコード修正

ライブラリのAPIが変化した場合は、アプリケーションのコードを変更する必要があります。

release noteやchangelogだけで正しい変更方法がわからない場合は、githubのcommits内の実際の変更差分や、公式ドキュメントも確認してください。 その変更内容も報告してください。

6-2. バージョン整合性の確認

PRで変更されたバージョン番号が、リポジトリ内の他の箇所でも参照されていないか確認してください。

以下の手順で調査してください：

1. PRのdiffから、変更されたバージョン番号を特定する
   • 変更前・変更後の両方を特定すること
2. 更新対象の種別を判断する
   • npmパッケージ、ランタイム、Docker base image等
3. PRで更新されたバージョンと揃えて、同時に更新するべき箇所が他にないかリポジトリ全体を調査する
   • 「4. ライブラリの使用箇所」で作成した参照箇所のリストも確認する
   • 加えて、例えばNode.jsのランタイム更新の場合、ローカル開発環境とproduction環境でバージョンを揃える必要がある。Dockerfileだけでなく、package.jsonやpackage-lock.jsonのengines・packageManager、.nvmrc、CI設定等も確認すること
   • 上の確認対象の例示はあくまで代表例です。状況に応じて漏れ抜けがないかよく考えましょう
4. 古いバージョンが残っている箇所があれば報告・修正する

注意：

• バージョン文字列の完全一致検索だけで「問題なし」と判断しないこと。範囲指定（22.x等）やエイリアスで管理されている場合がある
• 関連バージョンの対応関係は推測で判断せず、公式ドキュメントや実際の配布物を根拠に確認すること
  • 例：Node.jsバージョンに対応するnpmバージョン
• 外部アクセスの制限等で関連バージョンを確認できない場合は、「未確認」としてその旨を報告し、手動確認を促すこと

7. 興味深い更新

興味深い更新があれば、報告してください。 例えば以下のような内容です：

• アプリケーションにも応用できそうな新機能の実装や概念の発明
• プログラム言語や実行環境の新機能を活用した面白い機能の実装
• ライブラリの開発体制の変化

8. 過去の失敗の調査

このリポジトリにおいて、今回更新しようとしているライブラリに関する問題が発生した事がないか、調査してください。 pull requestとissueをライブラリ名で検索し、以下の例に当てはまるような事例があれば報告してください。

• pull requestをmergeせずにcloseした
• mergeしたが、不具合が発生してrevertした

問題が見つかった場合は、それが解決されているか確認してください。

最終確認

セクション間の整合性チェック

レポート全体を横断的に見直し、セクション間で矛盾や漏れがないか確認してください。

• あるセクションで読んだ・触れたファイルが、セクション4の参照箇所リストに含まれているか
• セクション4で列挙した参照箇所が、セクション6-2の整合性確認で全て検証されているか
• セクション3で確認した依存関係の情報と、セクション5の変更内容の要約に矛盾がないか

齟齬が見つかった場合は、該当セクションを修正してください。

出力形式の確認

レポートの形式を見直してください。出力先がGithubのコメント欄の場合は、それに適した形式で出力してください。

Tips: Githubのコメント欄に適した形式

外部リポジトリのissue番号やpull request番号は、完全なURL形式で記載する

#12345 ではなく https://github.com/:owner/:repo/issues/12345 と書く。 URLが左右の文字とくっつかないように、半角スペースを適宜付ける。こうすればクリッカブルなリンクとしてwebブラウザ上に描画される。

pull requestにラベルを付けて状況説明する

出力先がGithubのpull requestの場合は、レポート提出後に適切なラベルを付けてください。 例えばCVE番号が発行されているような重要なセキュリティアップデートのpull requestには、「security」ラベルを付けてください。

権限が不足している場合は報告する

あなたがGitHub Actions上で実行されているClaude Codeの場合、タスクを遂行するための権限が十分与えられていないかもしれません。 リポジトリの管理者が適切に対応するために、必要な権限を報告してください。

• 実行しようとしていたタスクの内容
• 不足していた権限。例えば
  • Claude CodeのallowedTools
  • Github Actionsのjobのpermissions