update-v8

workerd の V8 を更新する

V8 の更新はリスクの高い変更であり、パッチを慎重に管理し、マージコンフリクトの解決には人間の判断が必要です。このスキルでは、プロセス全体を説明します。開始前に、必ず開発者に対象バージョンを確認してください。

V8 の更新に関するリファレンスも参照してください。

各ステップで、必ず開発者とやり取りし、確認してください。 明示的な確認なしに、パッチの削除やハッシュの更新など、取り消せない操作を絶対に行わないでください。

---

前提条件

• depot_tools がインストールされ、$PATH に設定されていること（セットアップガイド）
• ローカルの V8 チェックアウトがあること（Bazel との混同を避けるため、workerd リポジトリの外に配置します）：

  mkdir v8 && cd v8 && fetch v8
  

---

ステップ 1：対象バージョンを特定する

chromiumdash.appspot.comで、Chrome Beta が使用している最新の V8 バージョンを確認します。対象の <new_version> を開発者に確認してください。

現在のバージョンは build/deps/v8.MODULE.bazel で確認できます。

VERSION = "14.5.201.6"    # example — check the actual file

これを <old_version> と呼びます。

ステップ 2：ローカルの V8 を現在の workerd バージョンに同期する

cd <path_to_v8>/v8
git checkout <old_version>
gclient sync

ステップ 3：workerd のパッチをブランチに適用する

git checkout -b workerd-patches
git am --keep-non-patch <path_to_workerd>/patches/v8/*

patches/v8/ には複数のパッチがあります。これらには、workerd 固有のカスタマイズが含まれています。

パッチのカテゴリ	例
シリアライズ	カスタムの ValueSerializer／Deserializer 形式バージョン、プロキシ／関数ホストオブジェクトのサポート
ビルドシステム	Windows／Bazel の修正、共有リンク、依存関係パスの上書き（fp16、fast_float、simdutf、dragonbox）
エンベッダーフック	Promise コンテキストのタグ付け、リクエスト間の Promise 解決、追加の isolate エンベッダースロット
バグ回避策	メモリリークアサートの無効化、遅いハンドルチェックの無効化、builtin-can-allocate の回避策
API の追加	String::IsFlat、AdjustAmountOfExternalAllocatedMemory の公開、追加の Exception コンストラクター
ICU／設定	ICU データのエクスポート、googlesource ICU バインディング、verify_write_barriers フラグ

ステップ 4：パッチを新しい V8 バージョンにリベースする

git rebase --onto <new_version> <old_version>

**ここが作業の大半を占めます。**コンフリクトが発生することを想定してください。主な注意点は次のとおりです。

• ビルドシステムのパッチ（依存関係のパス、Bazel 設定）は、上流の V8 がビルドを再構成する際に最も頻繁にコンフリクトします。
• API のパッチ（V8 クラスへの新しいメソッド）は、上流で周辺コードが変更されているとコンフリクトすることがあります。
• workerd の意図を必ず維持してください。コンフリクトを解決する前に、各パッチの内容を理解してください。パッチのファイル名は内容を表しています。
• 開発者の明示的な確認なしに、パッチを削除しないでください。
• コンフリクトを自動解決しないでください。人による確認が必要なものとして報告してください。V8 パッチのマージコンフリクトには、ほとんどの場合、人間の判断が必要です。

ステップ 5：パッチを再生成する

git format-patch --full-index -k --no-signature --no-stat --zero-commit <new_version>

これにより、現在のディレクトリに番号付きの .patch ファイルが生成されます。

ステップ 6：workerd のパッチを置き換える

パッチを置き換える前に、必ず担当者に確認してください。パッチが削除または追加された場合は、 担当者が変更を確認する必要があります。

rm <path_to_workerd>/patches/v8/*
cp *.patch <path_to_workerd>/patches/v8/

ステップ 7：build/deps/v8.MODULE.bazel を更新する

更新が必要な項目は 3 つです。

1. VERSION：<new_version> に設定します。

2. INTEGRITY：新しい tarball の sha256 ハッシュを計算します。

   curl -sL "https://github.com/v8/v8/archive/refs/tags/<new_version>.tar.gz" -o v8.tar.gz
   openssl dgst -sha256 -binary v8.tar.gz | openssl base64 -A
   

   形式："sha256-<base64_hash>="。または、ビルドを実行し、Bazel の不一致エラーから期待されるハッシュをコピーしてください。

3. PATCHES：パッチが追加、削除、または名前変更された場合は、リストを更新します。リストは、patches/v8/ 内のファイル名と順序も含めて完全に一致させる必要があります。

ステップ 8：V8 の依存関係を更新する

V8 は、build/deps/v8.MODULE.bazel と build/deps/deps.jsonc でバージョンが固定されている複数のライブラリに依存しています。ローカルの V8 チェックアウトにある DEPS ファイルでコミットバージョンを確認してください：

cat <path_to_v8>/v8/DEPS

確認して更新する依存関係：

依存関係	場所	注記
com_googlesource_chromium_icu	v8.MODULE.bazel（git_repository commit）	Chromium のフォークです。V8 の DEPS からコミットを更新します
perfetto	deps.jsonc（update-deps.py が管理）	V8 は Chromium 経由で依存しています。最新の GitHub リリースに更新しても安全です
simdutf	deps.jsonc（update-deps.py が管理）	V8 は Chromium 経由で依存しています。最新の GitHub リリースに更新しても安全です

deps.jsonc 内の依存関係については、更新スクリプトを使用できます：

python3 build/deps/update-deps.py perfetto
python3 build/deps/update-deps.py simdutf

このスクリプトは最新バージョンを取得し、整合性ハッシュを計算して、gen/ の MODULE.bazel フラグメントを再生成します。build/deps/gen/ 内のファイルを手動で編集しないでください。

ステップ 9：ビルドとテスト

# Full build
just build

# Full test suite
just test

以下の点に注意してください：

• V8 API の変更によるビルド失敗：V8 はバージョン間で API を非推奨にしたり、変更したりすることがあります。ビルド出力で非推奨警告を検索してください。影響を受けやすい一般的な領域：

  • src/workerd/jsg/ — V8 バインディングレイヤー。最も直接的な影響を受けます
  • src/workerd/api/ — V8 の型と直接やり取りする API
  • src/workerd/io/worker.c++ — Isolate の作成と設定

• 動作変更によるテスト失敗：V8 は、観測可能な JS の動作を変更することがあります。次を確認してください：

  • just test //src/workerd/jsg/... — JSG バインディングテスト
  • just test //src/workerd/api/tests/... — API テスト
  • Node.js 互換性テスト（just node-test）
  • Web Platform Tests（just wpt-test）

• 新しい V8 非推奨警告：これらは将来的な問題の兆候です。テストが通過した場合も、PR の説明に記載してください。

ステップ 10：コミットして提出する

変更をコミットし、レビューに出すようユーザーに促してください。

パッチの変更を人がレビューしていない状態で、絶対にレビュー用ブランチをプッシュしないでください。

ユーザー向けに PR の下書きテキストを用意することはできます。PR には次を含めてください：

• 更新した build/deps/v8.MODULE.bazel（バージョン、整合性、パッチリスト）
• 更新した patches/v8/ 内のパッチ
• 変更した場合は、更新した依存関係のバージョン
• V8 API の変更に対する C++ の修正
• 次を記載した PR の説明：旧バージョン、新バージョン、競合解決が必要だったパッチ、確認された非推奨警告、確認された動作変更

---

チェックリスト

• 対象の V8 バージョンを開発者に確認した
• ローカルの V8 をチェックアウトし、旧バージョンに同期した
• workerd のパッチを適用し、新バージョンにリベースした
• 人によるレビューのもとで競合を解決した（自動解決なし）
• git format-patch でパッチを再生成した
• patches/v8/ 内の旧パッチを新しいパッチに置き換えた
• v8.MODULE.bazel の VERSION を更新した
• v8.MODULE.bazel の INTEGRITY を更新した
• パッチを追加、削除、または名前変更した場合は PATCHES リストを更新した
• V8 の依存関係を確認して更新した（ICU、perfetto、simdutf）
• just build が成功した
• just test が成功した（または、失敗を文書化して説明した）
• 明示的な確認なしに新しいパッチを削除していない
• PR の説明にバージョン変更、競合解決、非推奨警告を記載した

---

トラブルシューティング

Bazel の整合性不一致：expected sha256-... but got sha256-... と表示された場合は、「got」のハッシュを INTEGRITY フィールドにコピーしてください。ハッシュの計算が誤っている場合や、GitHub によって tarball が再生成された場合に発生します。

パッチを適用できない：git am では問題なく適用されたパッチが Bazel で失敗する場合、git format-patch の出力が Bazel の想定と異なっています。--full-index -k --no-signature --no-stat --zero-commit フラグを使用したことを確認してください。また、パッチの順序が PATCHES リストと一致していることも確認してください。

ICU のビルド失敗：ICU は git_repository を介して取得される Chromium のフォークです。v8.MODULE.bazel のコミットが間違っていると、ICU でファイル不足エラーやコンパイルエラーが発生します。正しいコミットについては、V8 の DEPS ファイルを参照してください。

update-deps.py の実行失敗：このスクリプトはバージョンの取得にネットワークアクセスを必要とします。依存関係の GitHub リリース形式が変更された場合は、deps.jsonc でバージョンを手動で更新し、python3 build/deps/update-deps.py を実行してハッシュを再生成する必要があります。