shokai ライブラリ更新のレビュー手順書
ライブラリを更新する変更をレビューし、必要に応じてバージョン間のmigrationや、breaking changeへの対応も行う為の手順を説明します。 コマンドやファイルの具体例としてNode.jsを使って説明していますが、実際に変更されたライブラリやプログラム言語の常識に照らし合わせて適宜読み替えてください。
対象
- 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. 変更スコープの確認
このpull requestで何が変更されたか、その範囲を把握してください。
lock file差分から、更新・追加・削除されたパッケージを列挙してください。
- 件数が多い場合でも、主要な変更対象は漏れなく明示する
- 更新対象ライブラリとの関係が明確ではないパッケージの変更が含まれていたら、その旨を注記する
- この時点で安全性や影響範囲は断定しない。後続セクションで確認すべき注意点として扱う
例: npmの package-lock.json の場合、gh pr diff や git diff でlock file差分を取得する。個別パッケージの周辺コンテキストは grep -C15 '<パッケージ名>' package-lock.json で確認できる。
4. ライブラリの依存関係
ライブラリの依存関係を確認してください。
package-lock.jsonを読んで依存関係を確認してください。grep -C15 ライブラリ名 package-lock.json のようなコマンドが有効です。
- そのライブラリに依存している他のライブラリがあれば列挙する
- そのライブラリが依存している他のライブラリがあれば列挙する
5. ライブラリの使用箇所とバージョン情報
リポジトリ内で、そのライブラリや実行環境が参照・指定されている箇所を調査してください。
import文やrequire文だけでなく、設定ファイル・Dockerfile・CI設定・開発環境設定など、バージョンが指定されている箇所も調査対象に含めてください。
git grep ライブラリ名 に加えて、バージョン番号やパッケージ名での検索も行ってください。
調査結果は、参照箇所をファイル単位で一覧にまとめてください。このリストはセクション7-2「バージョン整合性の確認」の入力として使います。 セクション3・4等の他セクションで読んだファイルにもバージョン指定が含まれている場合があるので、漏らさずリストに含めてください。
6. 変更内容の要約
変更内容を要約してください。 ライブラリの公式サイトやGithubを参照し、release noteやchangelog、migration guideを詳しく読んで変更内容を把握してください。 機能追加やAPIの仕様変更のうち、特にアプリケーション側で使っている機能に関係がありそうな変更を抜き出して、報告してください。 変更前と後の間に含まれる、全バージョンの変更内容を1つずつ確認する必要があります。
重要：pull requestの概要欄に書かれている説明は誤っている可能性があるので、無視してください。現状のコードとdiffだけを参考にしてください。
7. コード・設定の更新
ライブラリや実行環境の更新に伴い、アプリケーションコード・設定ファイルの修正が必要か確認してください。 必要に応じてpull requestの作成を提案してください。
以下の2つの観点を区別して確認してください。
7-1. APIや仕様変更に伴うコード修正
ライブラリのAPIが変化した場合は、アプリケーションのコードを変更する必要があります。
release noteやchangelogだけで正しい変更方法がわからない場合は、githubのcommits内の実際の変更差分や、公式ドキュメントも確認してください。 その変更内容も報告してください。
7-2. バージョン整合性の確認
PRで変更されたバージョン番号が、リポジトリ内の他の箇所でも参照されていないか確認してください。
以下の手順で調査してください：
- PRのdiffから、変更されたバージョン番号を特定する
- 変更前・変更後の両方を特定すること
- 更新対象の種別を判断する
- npmパッケージ、ランタイム、Docker base image等
- PRで更新されたバージョンと揃えて、同時に更新するべき箇所が他にないかリポジトリ全体を調査する
- 「5. ライブラリの使用箇所」で作成した参照箇所のリストも確認する
- 加えて、例えばNode.jsのランタイム更新の場合、ローカル開発環境とproduction環境でバージョンを揃える必要がある。Dockerfileだけでなく、package.jsonやpackage-lock.jsonのengines・packageManager、.nvmrc、CI設定等も確認すること
- 上の確認対象の例示はあくまで代表例です。状況に応じて漏れ抜けがないかよく考えましょう
- 古いバージョンが残っている箇所があれば報告・修正する
注意：
- バージョン文字列の完全一致検索だけで「問題なし」と判断しないこと。範囲指定（
22.x等）やエイリアスで管理されている場合がある - 関連バージョンの対応関係は推測で判断せず、公式ドキュメントや実際の配布物を根拠に確認すること
- 例：Node.jsバージョンに対応するnpmバージョン
- 外部アクセスの制限等で関連バージョンを確認できない場合は、「未確認」としてその旨を報告し、手動確認を促すこと
8. 興味深い更新
興味深い更新があれば、報告してください。 例えば以下のような内容です：
- アプリケーションにも応用できそうな新機能の実装や概念の発明
- プログラム言語や実行環境の新機能を活用した面白い機能の実装
- ライブラリの開発体制の変化
9. 過去の失敗の調査
このリポジトリにおいて、今回更新しようとしているライブラリに関する問題が発生した事がないか、調査してください。 pull requestとissueをライブラリ名で検索し、以下の例に当てはまるような事例があれば報告してください。
- pull requestをmergeせずにcloseした
- mergeしたが、不具合が発生してrevertした
問題が見つかった場合は、それが解決されているか確認してください。
最終確認
セクション間の整合性チェック
レポート全体を横断的に見直し、セクション間で矛盾や漏れがないか確認してください。
- あるセクションで読んだ・触れたファイルが、セクション5の参照箇所リストに含まれているか
- セクション5で列挙した参照箇所が、セクション7-2の整合性確認で全て検証されているか
- セクション4で確認した依存関係の情報と、セクション6の変更内容の要約に矛盾がないか
- セクション3で列挙した変更パッケージのうち、セクション6のrelease note要約で根拠や意図が説明されていないものがないか。説明されていない変更があれば、未説明の変更としてレビュー上の注意点に含まれているか確認する
齟齬が見つかった場合は、該当セクションを修正してください。
出力形式の確認
レポートの形式を見直してください。出力先が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