electron-chromium-upgrade

Electron Chromium 升级：第一阶段

摘要

反复运行 e sync --3，并在出现补丁冲突时解决问题，直到命令成功。然后导出补丁并以原子方式提交更改。

成功标准

代码检查要求：

• 代码／补丁编辑：标题必须严格为 {CL-Number}: {upstream CL original title}，正文中必须包含 Ref: {URL}。
• 仅元数据补丁更新（哈希值／行号）：提交信息必须严格为 chore: update patches，且不含正文。

满足以下条件即表示第一阶段完成：

• e sync --3 以代码 0 退出（没有补丁失败）
• 按照提交指南提交所有更改

在满足这些标准之前不要停止。

重要 不要删除或跳过补丁，除非 100％ 确定该补丁已不再需要。复杂冲突或难以解决的问题应在穷尽其他所有选项后提交给用户。不要仅仅因为无法解决补丁就将其删除。

重要 绝不要使用 git am --skip，然后通过创建新提交来手动重新生成补丁。这会破坏原始补丁的作者信息、提交信息和在补丁序列中的位置。如果 git am --continue 报告“No changes”，请调查原因——这些更改很可能已通过先前冲突解决的三方合并被吸收。应将此情况提交给用户，而不是跳过补丁并重新创建。

上下文

自动化创建 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 标志启用三方合并）
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，但不会运行通常用于重新生成这些列表的 pre-commit hook，因此现在请手动运行生成器（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）→ 提交标题为 {CL-Number}: {upstream CL original title}，并包含一行 Ref:。其中，CL 是修改固定版本的上游提交。通过 DEPS 中对应依赖的新 SHA 在 Chromium 中查找该提交（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	克隆依赖项并使用三方合并应用补丁
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 并创建替代提交。该补丁的更改已被先前的三方合并解决吸收。这意味着较早的冲突解决引入了过多更改。请将情况告知用户以寻求指导——正确的修复可能需要更谨慎地重新处理之前的冲突解决，以确保每个补丁的更改彼此独立。

Electron Chromium 升级：第二阶段

摘要

反复运行 e build -k 999 -- --quiet，并在出现构建问题时逐一修复，直到构建成功。然后运行 e start --version 验证 Electron 能否启动，并以原子方式提交更改。

第一阶段完成后立即运行第二阶段。

成功标准

Linter 要求：

• 代码／补丁编辑：标题必须严格为 {CL-Number}: {upstream CL original title}，并在正文中包含 Ref: {URL}。
• 仅更新元数据的补丁（哈希值／行号）：提交消息必须严格为 chore: update patches，且不包含正文。

满足以下条件后，第二阶段才算完成：

• e build -k 999 -- --quiet 以代码 0 退出（无构建失败）
• 已运行 e start --version，检查 Electron 能否启动
• npm run gn-check 以代码 0 退出，且每个 script/gen-* 的 --check 均通过（参见步骤 7——这是 gn-check CI 作业的检查内容；即使构建成功，检查失败也会导致 roll 失败）
• 所有更改均按照提交指南提交

在满足这些标准之前，不要停止。不要删除代码或功能，也不要为了走捷径而注释掉代码。确保所有现有代码、逻辑和意图都能正常工作。

背景

roller/chromium/main 分支由自动化创建，用于更新 Electron 的 Chromium 依赖 SHA。尚未针对新旧版本之间的破坏性变更做任何处理。Chromium API 经常会重命名或重构。无论哪种情况，都必须更新 Electron 中的代码以适应 Chromium 的变更；应尽量避免修改 Chromium 中的代码来修复 Electron 的构建问题。

关键目录：

• 当前目录：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 作业。 每次 roll 时，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（或 include），然后重新运行检查。CI 会在所有三个平台上检查 testing 和 release 图，因此，即使某个 include 受另一个平台的 BUILDFLAG 保护，仍可能在该平台失败；如果本地检查通过而 CI 失败，请查看被包含头文件的 BUILD.gn 可见性／deps 设置。
   • gen-* 的 --check 失败表示派生列表已过期：运行生成器（不带 --check），并按照 Phase One 第 5 步提交。
8. 运行 git status，检查 Chromium 仓库中是否有待处理的更改
   • 如果有更改，请按照下方“A. 补丁修复”中的说明，将这些修改正确提交到相应的补丁文件中
9. 最终提交自检：针对此次升级新增的提交（即 chore: bump chromium in DEPS 之后的所有提交）运行 git log --format='%h %B'，并确认每个上游 CL 恰好由一个非 fixup 提交引用——检查完整提交消息，而不仅是标题，因为 Ref: 行位于提交正文中。如果某个 CL 出现在多个非 fixup 提交中，请按照 references/phase-two-commit-guidelines.md，使用 git commit --fixup 并通过 autosquash rebase 合并提交

命令参考

命令	用途
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	对 Electron 目标运行 gn check，与 gn-check CI 作业的运行方式相同

两种构建修复

A. 补丁修复（针对 chromium_src 中的文件或已打补丁的 Chromium 文件）

如果错误出现在 Electron 打补丁的文件中（使用 grep -l "filename" patches/chromium/*.patch 检查）：

1. 在 Chromium 源代码树中编辑文件（例如 /src/chrome/browser/...）
2. 创建一个针对原始补丁提交的 fixup 提交：

   cd ..  # to chromium repo
   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 提交更新后的补丁文件。

要查找要修复的原始补丁提交：git log --oneline | grep -i "keyword from patch name"

变基的基础提交是应用补丁之前的 Chromium 提交。检查 refs/patches/upstream-head 引用以查找该提交。

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 的提交格式

在工作流步骤中提及时，请阅读这些文件。