electron-chromium-upgrade

Electron Chromium のアップグレード：フェーズ 1

概要

e sync --3 を繰り返し実行し、パッチの競合が発生したら解決して、成功するまで続けます。その後、パッチをエクスポートし、変更をまとめてコミットします。

成功条件

リンター要件：

• コード／パッチの編集：タイトルは {CL-Number}: {upstream CL original title} と完全に一致させ、本文に Ref: {URL} を含めます。
• メタデータのみのパッチ更新（ハッシュ／行番号）：メッセージは本文なしの chore: update patches と完全に一致させます。

以下を満たした時点でフェーズ 1 は完了です。

• e sync --3 が終了コード 0 で終了する（パッチの失敗がない）
• コミットガイドラインに従ってすべての変更がコミットされている

これらの条件を満たすまで作業を続けてください。

重要 パッチが不要になったことを 100% 確信できない限り、パッチを削除したりスキップしたりしないでください。複雑な競合や解決が難しい問題は、ほかのすべての手段を尽くした後でユーザーに提示してください。解決できないという理由だけでパッチを削除しないでください。

重要 git am --skip を使ってから、新しいコミットを作成してパッチを手動で再作成することは絶対に避けてください。元のパッチの作成者情報、コミットメッセージ、シリーズ内の位置が失われます。git am --continue が「No changes」と報告した場合は、その理由を調査してください。変更は、先行する競合解決の 3-way マージによってすでに取り込まれている可能性があります。スキップして再作成するのではなく、この状況をユーザーに提示してください。

コンテキスト

roller/chromium/main ブランチは、Electron の Chromium 依存関係の SHA を更新する自動化によって作成されます。旧バージョンと新バージョンの間の破壊的変更への対応作業は行われていません。

主なディレクトリ：

• 現在のディレクトリ：Electron リポジトリ（ここで常に e コマンドを実行します）
• ..（親ディレクトリ）：Chromium リポジトリ（ほとんどのパッチを適用する場所）
• patches/：適用先ごとに整理されたパッチファイル
• docs/development/patches.md：パッチシステムのドキュメント

事前確認

各アップグレードセッションの開始時に、次の手順を一度実行します。

1. rerere キャッシュをクリアする（有効な場合）：electron リポジトリと .. リポジトリの両方で git rerere clear を実行します。以前の試行で記録された古い解決内容が、誤ったマージを気づかれないまま適用する可能性があります。
2. pre-commit フックがインストールされていることを確認する：git config core.hooksPath の出力が .husky/_ であり、.husky/_/pre-commit が存在することを確認します（husky は .git/hooks/ を使用しません）。条件を満たさない場合は、yarn husky を実行してインストールします。このフックは lint-staged を実行し、C++ ファイルの clang-format と、すべてのコミットでの script/lint-roller-chromium-changes.mjs の実行を処理します。

ワークフロー

1. e sync --3 を実行します（--3 フラグは 3-way マージを有効にします。常に必要です）。
2. 成功した場合 → ステップ 5 に進みます。
3. パッチの適用に失敗した場合：
   • エラー出力から対象リポジトリとパッチを特定します。
   • 失敗の原因を分析します（references/patch-analysis.md を参照）。
   • 対象リポジトリの作業ディレクトリで競合を解決します。
   • 該当するリポジトリで git am --continue を実行します。
   • そのリポジトリのすべてのパッチが適用されるまで繰り返します。
   • 重要：git am --continue が成功したら、修正をエクスポートするために必ず e patches {target} を実行してください。
   • ステップ 1 に戻ります。
4. e sync --3 が成功したら、e patches all を実行します。
5. 派生ファイルリストを再生成します。 Electron は Chromium の DEPS ピンを反映したリストをチェックインしており、いずれかが古いと、すべてのプラットフォームで gn-check CI ジョブがロールに失敗します。ローラーボットは、通常これらを再生成するプリコミットフックを実行せずに DEPS を更新するため、今すぐ手動でジェネレーターを実行してください（gn-check ジョブは各ジェネレーターの --check 形式を実行します）。

   node script/gen-hunspell-filenames.js   # filenames.hunspell.gni (from ../third_party/hunspell_dictionaries)
   node script/gen-libc++-filenames.js     # filenames.libcxx.gni / filenames.libcxxabi.gni
   node script/gen-siso-revision.js        # build/siso_revision (the gen_siso_revision sync hook usually did this already)
   node script/gen-filenames.mts --check   # fails only if lib/ or docs/api changed; regenerate without --check if it does
   

   次に git status を実行し、変更された各ファイルを個別にコミットします。
   • build/siso_revision → chore: update siso revision（タイトルは完全一致、本文なし）。CI はこのファイルを使って siso をビルドします。
   • filenames.libcxx.gni → chore: update libc++ filenames（タイトルは完全一致、本文なし。このファイルのみ）。
   • filenames.hunspell.gni（および専用パターンがない filenames.libcxxabi.gni）→ Ref: 行を含む {CL-Number}: {upstream CL original title} コミット。CL はピンを移動した上流コミットです。Chromium の DEPS にある依存関係の新しい SHA から見つけてください（hunspell は src/third_party/hunspell_dictionaries、libc++abi は src/third_party/libc++abi/src）：

     cd .. && git log --format='%h %s%n%(trailers:key=Reviewed-on,valueonly)' refs/patches/upstream-head -S<new-dep-sha> -- DEPS
     

6. 今すぐ references/phase-one-commit-guidelines.md を読み、その指示に正確に従って変更をコミットします。

コマンドのリファレンス

コマンド	目的
e sync --3	依存関係をクローンし、3-way マージでパッチを適用する
git am --continue	競合を解決した後に続行する（対象リポジトリで実行）
e patches {target}	対象リポジトリのコミットをパッチファイルにエクスポートする
e patches all	すべての対象のすべてのパッチをエクスポートする
e patches {target} --commit-updates	パッチをエクスポートし、簡単な変更を自動コミットする
e patches --list-targets	対象と設定パスを一覧表示する

パッチシステムのメンタルモデル

patches/{target}/*.patch  →  [e sync --3]  →  target repo commits
                          ←  [e patches]   ←

パッチを編集するタイミング

状況	対応
git am の競合を解決中	対象リポジトリで修正し、その後 git am --continue を実行する
競合の発生中以外にパッチを変更する場合	.patch ファイルを直接編集する
新しいパッチを作成する場合（まれ。避けること）	対象リポジトリでコミットし、その後 e patches {target} を実行する

新しいパッチを作成するよりも、99% の場合は既存のパッチを修正してください。

パッチ修正のルール

1. 作者情報を保持する：TODO コメント内の元の作者（パッチの From: フィールド）を維持します。
2. TODO の担当者を変更しない：TODO(name) の元の名前を維持します。
3. 説明を更新する：上流で変更があった場合（例：DCHECK → CHECK_IS_TEST）、現在の状態を反映するようにパッチのコミットメッセージを更新します。
4. パッチをスキップして作り直さない：git am --continue が「No changes — did you forget to use 'git add'?」と表示した場合、git am --skip を実行して置き換えのコミットを作成してはいけません。パッチの変更は、以前の 3-way マージの解決ですでに取り込まれています。これは、前の競合解決で変更を取り込みすぎたことを意味します。状況をユーザーに提示して指示を仰いでください。適切な修正には、各パッチの変更を分けたままにできるよう、以前の解決をより慎重にやり直す必要がある場合があります。

Electron Chromium アップグレード：フェーズ 2

概要

e build -k 999 -- --quiet を繰り返し実行し、問題が発生するたびに修正して、ビルドが成功するまで続けます。次に e start --version を実行して Electron が起動することを確認し、変更を一括してコミットします。

フェーズ 1 の完了後、すぐにフェーズ 2 を実行してください。

成功基準

リンターの要件：

• コード／パッチの編集：タイトルは正確に {CL-Number}: {upstream CL original title} とし、本文に Ref: {URL} を含める必要があります。
• メタデータのみのパッチ更新（ハッシュ／行番号）：メッセージは正確に chore: update patches とし、本文は付けません。

以下を満たした時点で、第 2 フェーズは完了です。

• e build -k 999 -- --quiet が終了コード 0 で終了する（ビルド失敗がない）
• Electron の起動を確認するため、e start --version を実行している
• npm run gn-check が終了コード 0 で終了し、すべての script/gen-* の --check が成功する（手順 7 を参照。これは gn-check CI ジョブで実行されるもので、ビルドとは独立してロール全体を失敗させます）
• すべての変更がコミットガイドラインに従ってコミットされている

これらの基準を満たすまで作業を中断しないでください。コードや機能を削除しないでください。近道としてコードをコメントアウトしないでください。既存のコード、ロジック、意図をすべて機能させてください。

コンテキスト

roller/chromium/main ブランチは、Electron の Chromium 依存関係の SHA を更新するために自動作成されます。旧バージョンと新バージョン間の破壊的変更への対応は行われていません。Chromium API は頻繁に名前が変更されたり、リファクタリングされたりします。どの場合も、Chromium の変更に対応できるよう Electron のコードを更新し、Electron のビルドを修正するために Chromium のコードを変更することは極力避けてください。

主なディレクトリ：

• 現在のディレクトリ：Electron リポジトリ（e コマンドは常にここで実行してください）
• ..（親ディレクトリ）：Chromium リポジトリ（ビルドの問題を修正するためにこのコードには手を加えず、コンテキストを把握するために読むだけにしてください）

ワークフロー

1. e build -k 999 -- --quiet を実行します（--quiet フラグを指定すると、ターゲットごとのステータス行が抑制され、エラーと最終結果のみが表示されます）。
2. 成功した場合 → ステップ 6 に進みます。
3. ビルドに失敗した場合：
   • コンパイルエラーメッセージから「electron」内の該当ファイルを特定します。
   • 失敗の原因を分析します。
   • Chromium の変更に合わせて Electron のコードを調整し、ビルドの問題を修正します。
   • e build -t {target_that_failed}.o を実行し、修正対象の失敗したターゲットのみをビルドします。
     • ビルドログの失敗行から target_that_failed を特定できます。例：FAILED: 2e506007-8d5d-4f38-bdd1-b5cd77999a77 "./obj/electron/chromium_src/chrome/process_singleton_posix.o" CXX obj/electron/chromium_src/chrome/process_singleton_posix.o の場合、ターゲット名は obj/electron/chromium_src/chrome/process_singleton_posix.o です。
   • 今すぐ references/phase-two-commit-guidelines.md を読み、指示に正確に従って変更をコミットしてください。
   • ステップ 1 に戻ります。
4. 重要：コミット（特にパッチのコミット）の後は、必ずすぐに electron リポジトリで git status を実行します。
   • インデックス／ハンクヘッダーのみが変更された、ほかの変更済み .patch ファイルがないか確認します。
   • これらは修正の影響を受けた依存パッチです。次のコマンドですぐにコミットします：git commit -am "chore: update patches"
5. ステップ 1 に戻ります。
6. e build が成功したら、e start --version を実行します。
7. gn-check CI ジョブをローカルで実行します。 CI では各ロール時に linux-gn-check、macos-gn-check、windows-gn-check が実行されます。ビルドが成功しても、これらが通るとは限りません。electron ディレクトリで、ジョブとまったく同じコマンドを実行してください（.github/workflows/pipeline-segment-electron-gn-check.yml を参照）。

   npm run gn-check                          # 現在の out ディレクトリに対して Electron ターゲットの `gn check` を実行
   node script/gen-hunspell-filenames.js --check
   node script/gen-libc++-filenames.js --check
   node script/gen-siso-revision.js --check
   node script/gen-filenames.mts --check
   

   • gn check に失敗した場合、deps に含まれていないターゲットからヘッダーがインクルードされていることを意味します。Electron の BUILD.gn／filenames.gni（またはインクルード）を修正してから、再実行してください。CI では 3 つすべてのプラットフォームで testing と release のグラフをチェックするため、別のプラットフォームの BUILDFLAG でガードされたインクルードでも失敗することがあります。ローカルのチェックは成功するのに CI で失敗する場合は、インクルードされたヘッダーの BUILD.gn にある可視性／依存関係を確認してください。
   • gen-* の --check に失敗した場合、派生リストが古くなっています。ジェネレーターを --check なしで実行し、Phase One のステップ 5 に従ってコミットしてください。
8. git status を実行して、Chromium リポジトリに保留中の変更があるか確認します。
   • 変更がある場合は、「A. Patch Fixes」の以下の指示に従い、該当するパッチファイルに変更を正しくコミットしてください。
9. 最終コミットのセルフチェック：このアップグレードで追加したコミット（chore: bump chromium in DEPS コミット以降のすべて）に対して git log --format='%h %B' を実行し、各アップストリーム CL が fixup 以外のコミットでちょうど 1 回だけ参照されていることを確認します。タイトルだけでなく、コミットメッセージ全体を確認してください。Ref: 行はコミット本文に含まれるためです。CL が fixup 以外の複数のコミットに記載されている場合は、references/phase-two-commit-guidelines.md に従い、git commit --fixup と autosquash リベースでまとめてください。

コマンドリファレンス

コマンド	用途
e build -k 999 -- --quiet	Electron をビルドし、エラーがあっても続行して、ステータス行を抑制します
e build -t {target}.o	修正を検証するため、特定のターゲットのみをビルドします
e build --no-remote -t {target}.o	同じターゲットをローカルでビルドします。リモート実行環境が Electron のコードではなく、ツールチェーン／モジュール入力で失敗する場合に使用します
e start --version	ビルド成功後に Electron が起動することを検証します
npm run gn-check	gn-check CI ジョブと同様に、Electron ターゲット全体に対して gn check を実行します

ビルド修正の 2 つの種類

A. パッチ修正（chromium_src またはパッチが適用された Chromium ファイル）

Electron がパッチを適用しているファイルでエラーが発生した場合は、grep -l "filename" patches/chromium/*.patch で確認してください。

1. Chromium のソースツリー内のファイルを編集します（例：/src/chrome/browser/...）。
2. 元のパッチコミットを対象に fixup コミットを作成します。

   cd ..  # chromium リポジトリへ移動
   git add <modified-file>
   git commit --fixup=<original-patch-commit-hash>
   GIT_SEQUENCE_EDITOR=: git rebase --autosquash --autostash -i <commit>^
   

3. 更新したパッチをエクスポートします：e patches chromium
4. references/phase-one-commit-guidelines.md に従って、更新したパッチファイルをコミットします。

fixup 対象の元のパッチコミットを見つけるには、git log --oneline | grep -i "keyword from patch name" を実行します。

リベースのベースコミットは、パッチが適用される前の Chromium コミットです。refs/patches/upstream-head ref を確認して見つけてください。

B. Electron コードの修正（shell/、electron/ などのファイル）

Electron 独自のソースコードでエラーが発生した場合：

1. electron リポジトリ内のファイルを直接編集します。
2. 直接コミットします（パッチのエクスポートは不要です）。

重要：コミット前に読むこと

• Phase One のコミットを行う前に必ず：references/phase-one-commit-guidelines.md を読みます。
• Phase Two のコミットを行う前に必ず：references/phase-two-commit-guidelines.md を読みます。

スキルディレクトリの構成

このスキルには、references/ に追加の参考ファイルがあります。

• patch-analysis.md - パッチ失敗の分析方法
• phase-one-commit-guidelines.md - Phase One のコミット形式
• phase-two-commit-guidelines.md - Phase Two のコミット形式

ワークフローの手順で参照されている場合は、これらを読んでください。