electron-chromium-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Electron Chromium Upgrade: Phase One

Electron Chromium版本升级：第一阶段

Summary

概述

Run

e sync --3

repeatedly, fixing patch conflicts as they arise, until it succeeds. Then run

e patches all

and commit changes atomically.

重复运行

e sync --3

，出现补丁冲突时进行修复，直到命令执行成功。然后运行

e patches all

并以原子方式提交变更。

Success Criteria

成功标准

Phase One is complete when:

```
e sync --3
```
exits with code 0 (no patch failures)
```
e patches all
```
has been run to export all changes
All changes are committed per the commit guidelines below

Do not stop until these criteria are met.

CRITICAL Do not delete or skip patches unless 100% certain the patch is no longer needed. Complicated conflicts or hard to resolve issues should be presented to the user after you have exhausted all other options. Do not delete the patch just because you can't solve it.

第一阶段完成的标志：

```
e sync --3
```
以代码0退出（无补丁应用失败）
已运行
```
e patches all
```
导出所有变更
所有变更均按照下文的提交指南完成提交

未满足以上标准前请勿停止操作。

重要提示：除非100%确定补丁已不再需要，否则请勿删除或跳过补丁。如果遇到复杂冲突或难以解决的问题，在尝试所有其他方法后再告知用户，不要因为无法解决就删除补丁。

Context

背景

The

roller/chromium/main

branch is created by automation to update Electron's Chromium dependency SHA. No work has been done to handle breaking changes between the old and new versions.

Key directories:

Current directory: Electron repo (always run
```
e
```
commands here)
```
..
```
(parent): Chromium repo (where most patches apply)
```
patches/
```
: Patch files organized by target
```
docs/development/patches.md
```
: Patch system documentation

roller/chromium/main

分支由自动化工具创建，用于更新Electron的Chromium依赖SHA值。该分支尚未处理新旧版本之间的破坏性变更。

关键目录：

当前目录：Electron仓库（所有
```
e
```
命令均在此目录运行）
```
..
```
（父目录）：Chromium仓库（大多数补丁应用于此）
```
patches/
```
：按目标分类的补丁文件
```
docs/development/patches.md
```
：补丁系统文档

Workflow

工作流

Delete the
```
.git/rr-cache
```
in both the
```
electron
```
and
```
..
```
folder to ensure no accidental rerere replays occur from before this upgrade phase attempt started
Run
```
e sync --3
```
(the
```
--3
```
flag enables 3-way merge, always required)
If succeeds → skip to step 6
If patch fails:
- Identify target repo and patch from error output
- Analyze failure (see references/patch-analysis.md)
- Fix conflict in target repo's working directory
- Run
```
git am --continue
```
  in affected repo
- Repeat until all patches for that repo apply
- IMPORTANT: Once
```
git am --continue
```
  succeeds you MUST run
```
e patches {target}
```
  to export fixes
- Return to step 1
When
```
e sync --3
```
succeeds, run
```
e patches all
```
Read
references/phase-one-commit-guidelines.md
NOW, then commit changes following those instructions exactly.

Before committing any Phase One changes, you MUST read

references/phase-one-commit-guidelines.md

and follow its instructions exactly.

删除Electron仓库和
```
..
```
目录下的
```
.git/rr-cache
```
，确保本次升级尝试不会意外重放之前的rerere记录
运行
```
e sync --3
```
（
```
--3
```
标志启用三方合并，为必填项）
如果执行成功 → 跳至步骤6
如果补丁应用失败：
- 从错误输出中识别目标仓库和补丁
- 分析失败原因（参考references/patch-analysis.md）
- 在目标仓库的工作目录中修复冲突
- 在受影响的仓库中运行
```
git am --continue
```
- 重复操作，直到该仓库的所有补丁均成功应用
- 重要：
```
git am --continue
```
  执行成功后，必须运行
```
e patches {target}
```
  导出修复内容
- 返回步骤1
当
```
e sync --3
```
执行成功后，运行
```
e patches all
```
立即阅读
references/phase-one-commit-guidelines.md
，然后严格按照其中的说明提交变更

在提交任何第一阶段的变更前，必须阅读

references/phase-one-commit-guidelines.md

并严格遵循其指示。

Commands Reference

命令参考

Command	Purpose
`e sync --3`	Clone deps and apply patches with 3-way merge
`git am --continue`	Continue after resolving conflict (run in target repo)
`e patches {target}`	Export commits from target repo to patch files
`e patches all`	Export all patches from all targets
`e patches --list-targets`	List targets and config paths

命令	用途
`e sync --3`	克隆依赖并通过三方合并应用补丁
`git am --continue`	解决冲突后继续补丁应用（在目标仓库中运行）
`e patches {target}`	将目标仓库的提交导出为补丁文件
`e patches all`	导出所有目标仓库的补丁
`e patches --list-targets`	列出所有目标及配置路径

Patch System Mental Model

补丁系统心智模型

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

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

When to Edit Patches

何时编辑补丁

Situation	Action
During active `git am` conflict	Fix in target repo, then `git am --continue`
Modifying patch outside conflict	Edit `.patch` file directly
Creating new patch (rare, avoid)	Commit in target repo, then `e patches {target}`

Fix existing patches 99% of the time rather than creating new ones.

场景	操作
`git am` 冲突处理中	在目标仓库中修复，然后运行 `git am --continue`
冲突外的补丁修改	直接编辑 `.patch` 文件
创建新补丁（罕见，尽量避免）	在目标仓库中提交，然后运行 `e patches {target}`

优先修复现有补丁（99%的场景），而非创建新补丁。

Patch Fixing Rules

补丁修复规则

Preserve authorship: Keep original author in TODO comments (from patch
```
From:
```
field)
Never change TODO assignees:
```
TODO(name)
```
must retain original name
Update descriptions: If upstream changed (e.g.,
```
DCHECK
```
→
```
CHECK_IS_TEST
```
), update patch commit message to reflect current state

保留作者信息：在TODO注释中保留原作者信息（来自补丁的
```
From:
```
字段）
勿修改TODO负责人：
```
TODO(name)
```
必须保留原名称
更新描述：如果上游有变更（例如
```
DCHECK
```
→
```
CHECK_IS_TEST
```
），更新补丁的提交信息以反映当前状态

Final Deliverable

最终交付物

After Phase One, write a summary of every change: what was fixed, why, reasoning, and Chromium CL links.

第一阶段完成后，撰写所有变更的摘要：修复内容、原因、推理过程以及Chromium CL链接。

Electron Chromium Upgrade: Phase Two

Electron Chromium版本升级：第二阶段

Summary

概述

Run

e build -k 999

repeatedly, fixing build issues as they arise, until it succeeds. Then run

e start --version

to validate Electron launches and commit changes atomically.

Run Phase Two immediately after Phase One is complete.

重复运行

e build -k 999

，出现构建问题时进行修复，直到命令执行成功。然后运行

e start --version

验证Electron可正常启动，并以原子方式提交变更。

第一阶段完成后立即启动第二阶段。

Success Criteria

成功标准

Phase Two is complete when:

```
e build -k 999
```
exits with code 0 (no build failures)
```
e start --version
```
has been run to check Electron launches
All changes are committed per the commit guidelines below

Do not stop until these criteria are met. Do not delete code or features, never comment out code in order to take short cut. Make all existing code, logic and intention work.

第二阶段完成的标志：

```
e build -k 999
```
以代码0退出（无构建失败）
已运行
```
e start --version
```
检查Electron可正常启动
所有变更均按照下文的提交指南完成提交

未满足以上标准前请勿停止操作。请勿删除代码或功能，切勿通过注释代码走捷径。确保所有现有代码、逻辑和意图均可正常工作。

Context

背景

The

roller/chromium/main

branch is created by automation to update Electron's Chromium dependency SHA. No work has been done to handle breaking changes between the old and new versions. Chromium APIs frequently are renamed or refactored. In every case the code in Electron must be updated to account for the change in Chromium, strongly avoid making changes to the code in chromium to fix Electrons build.

Key directories:

Current directory: Electron repo (always run
```
e
```
commands here)
```
..
```
(parent): Chromium repo (do not touch this code to fix build issues, just read it to obtain context)

roller/chromium/main

分支由自动化工具创建，用于更新Electron的Chromium依赖SHA值。该分支尚未处理新旧版本之间的破坏性变更。Chromium API经常会被重命名或重构。无论何种情况，都必须更新Electron的代码以适配Chromium的变更，强烈避免修改Chromium代码来修复Electron的构建问题。

关键目录：

当前目录：Electron仓库（所有
```
e
```
命令均在此目录运行）
```
..
```
（父目录）：Chromium仓库（仅用于获取上下文，请勿修改此目录下的代码来修复构建问题）

Workflow

工作流

Run
```
e build -k 999
```
(the
```
-k 999
```
flag is a flag to ninja to say "do not stop until you find that many errors" it is an attempt to get as much error context as possible for each time we run build)
If succeeds → skip to step 6
If build fails:
- Identify underlying file in "electron" from the compilation error message
- Analyze failure
- Fix build issue by adapting Electron's code for the change in Chromium
- Run
```
e build -t {target_that_failed}.o
```
  to build just the failed target we were specifically fixing
  - You can identify the target_that_failed from the failure line in the build log. E.g.
```
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
```
    the target name is
```
obj/electron/chromium_src/chrome/process_singleton_posix.o
```
- Read
  references/phase-two-commit-guidelines.md
  NOW, then commit changes following those instructions exactly.
- Return to step 1
CRITICAL: After ANY commit (especially patch commits), immediately run
```
git status
```
in the electron repo
- Look for other modified
```
.patch
```
  files that only have index/hunk header changes
- These are dependent patches affected by your fix
- Commit them immediately with:
```
git commit -am "chore: update patch hunk headers"
```
- This prevents losing track of necessary updates
Return to step 1
When
```
e build
```
succeeds, run
```
e start --version
```
Check if you have any pending changes in the Chromium repo by running
```
git status
```
- If you have changes follow the instructions below in "A. Patch Fixes" to correctly commit those modifications into the appropriate patch file

Before committing any Phase Two changes, you MUST read

references/phase-two-commit-guidelines.md

and follow its instructions exactly.

运行
```
e build -k 999
```
（
```
-k 999
```
是ninja的标志，表示"找到999个错误后再停止"，旨在每次运行构建时获取尽可能多的错误上下文）
如果执行成功 → 跳至步骤6
如果构建失败：
- 从编译错误信息中定位Electron仓库中的相关文件
- 分析失败原因
- 通过调整Electron代码适配Chromium的变更来修复构建问题
- 运行
```
e build -t {target_that_failed}.o
```
  仅构建我们修复的失败目标
  - 可从构建日志的失败行中识别目标名称。例如：
```
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
重要：任何提交后（尤其是补丁提交），立即在Electron仓库中运行
```
git status
```
- 检查是否有其他仅修改了索引/块头的
```
.patch
```
  文件
- 这些是受你的修复影响的依赖补丁
- 立即使用以下命令提交：
```
git commit -am "chore: update patch hunk headers"
```
- 这可避免遗漏必要的更新
返回步骤1
当
```
e build
```
执行成功后，运行
```
e start --version
```
在Chromium仓库中运行
```
git status
```
检查是否有未提交的变更
- 如果有变更，请按照下文"A. 补丁修复"中的说明，将修改正确提交到对应的补丁文件中

在提交任何第二阶段的变更前，必须阅读

references/phase-two-commit-guidelines.md

并严格遵循其指示。

Build Error Detection

构建错误检测

When monitoring

e build -k 999

output, filter for errors using this regex pattern: error:|FAILED:|fatal:|subcommand failed|build finished

The build output is extremely verbose. Filtering is essential to catch errors quickly.

监控

e build -k 999

输出时，使用以下正则表达式过滤错误： error:|FAILED:|fatal:|subcommand failed|build finished

构建输出非常冗长，过滤操作是快速定位错误的关键。

Commands Reference

命令参考

Command	Purpose
`e build -k 999`	Builds Electron and won't stop until either all targets attempted or 999 errors found
`e build -t {target}.o`	Build just one specific target to verify a fix
`e start --version`	Validate Electron launches after successful build

命令	用途
`e build -k 999`	构建Electron，直到所有目标构建完成或找到999个错误才停止
`e build -t {target}.o`	仅构建指定目标以验证修复效果
`e start --version`	构建成功后验证Electron可正常启动

Two Types of Build Fixes

两类构建修复

A. Patch Fixes (for files in chromium_src or patched Chromium files)

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

When the error is in a file that Electron patches (check with

grep -l "filename" patches/chromium/*.patch

Edit the file in the Chromium source tree (e.g.,
```
/src/chrome/browser/...
```
)

Create a fixup commit targeting the original patch commit:

bash

cd ..  # to chromium repo
git add <modified-file>
git commit --fixup=<original-patch-commit-hash>
GIT_SEQUENCE_EDITOR=: git rebase --autosquash --autostash -i <commit>^

Export the updated patch: e patches chromium
Commit the updated patch file in the electron repo following the
```
references/phase-one-commit-guidelines.md
```
, then commit changes following those instructions exactly. READ THESE GUIDELINES BEFORE COMMITTING THESE CHANGES

To find the original patch commit to fixup:

git log --oneline | grep -i "keyword from patch name"

The base commit for rebase is the Chromium commit before patches were applied. Find it by checking the

refs/patches/upstream-head

ref.

B. Electron Code Fixes (for files in shell/, electron/, etc.)

When the error is in Electron's own source code:

Edit files directly in the electron repo
Commit directly (no patch export needed)

Dependent Patch Updates

IMPORTANT: When you modify a patch, other patches that apply to the same file may have their hunk headers invalidated. After committing a patch fix:

Run git status in the electron repo
Look for other modified .patch files with just index/hunk header changes
Commit these with: git commit -m "chore: update patch hunk headers"

当错误出现在Electron打补丁的文件中时（可通过

grep -l "filename" patches/chromium/*.patch

检查）：

在Chromium源码树中编辑文件（例如
```
/src/chrome/browser/...
```
）

创建针对原补丁提交的修正提交：

bash

cd ..  # 进入Chromium仓库
git add <modified-file>
git commit --fixup=<original-patch-commit-hash>
GIT_SEQUENCE_EDITOR=: git rebase --autosquash --autostash -i <commit>^

导出更新后的补丁：e patches chromium
严格按照
```
references/phase-one-commit-guidelines.md
```
中的说明，在Electron仓库中提交更新后的补丁文件。提交前务必阅读这些指南

查找原补丁提交的方法：

git log --oneline | grep -i "补丁名称中的关键词"

变基的基准提交是补丁应用前的Chromium提交，可通过

refs/patches/upstream-head

引用查找。

B. Electron代码修复（针对shell/、electron/等目录下的文件）

当错误出现在Electron自身的源码中时：

直接在Electron仓库中编辑文件
直接提交（无需导出补丁）

Critical: Read Before Committing

依赖补丁更新

Before ANY Phase One commits: Read

references/phase-one-commit-guidelines.md

Before ANY Phase Two commits: Read

references/phase-two-commit-guidelines.md

重要：当你修改某个补丁时，应用于同一文件的其他补丁的块头可能会失效。提交补丁修复后：

在Electron仓库中运行git status
检查是否有其他仅修改了索引/块头的.patch文件
使用以下命令提交：git commit -m "chore: update patch hunk headers"

Skill Directory Structure

提交前必读

This skill has additional reference files in

references/

patch-analysis.md - How to analyze patch failures
phase-one-commit-guidelines.md - Commit format for Phase One
phase-two-commit-guidelines.md - Commit format for Phase Two

Read these when referenced in the workflow steps.

提交任何第一阶段变更前：阅读
```
references/phase-one-commit-guidelines.md
```
提交任何第二阶段变更前：阅读
```
references/phase-two-commit-guidelines.md
```

—

技能目录结构

—

本技能在

references/

目录下包含额外的参考文件：

patch-analysis.md - 补丁失败分析方法
phase-one-commit-guidelines.md - 第一阶段提交格式
phase-two-commit-guidelines.md - 第二阶段提交格式

在工作流步骤中提及这些文件时，请阅读对应的内容。