桌面应用浏览器升级

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

总结

运行e sync --3反复进行,修复出现的补丁冲突,直到成功。然后导出补丁并自动提交更改。

成功标准

Linter 要求:代码/补丁编辑:标题必须准确{CL-Number}: {upstream CL original title}与Ref: {URL}在身体里。仅元数据补丁更新(哈希/行号):消息必须准确无误chore: update patches没有身体。第一阶段完成时:e sync --3退出并显示代码 0(无补丁失败)

背景

的roller/chromium/main分支是通过自动化创建的,以更新 Electron 的 Chromium 依赖项 SHA。尚未开展任何工作来处理新旧版本之间的重大更改。关键目录:当前目录:Electron repo(始终运行e命令在这里)..(父级):Chromium 存储库(大多数补丁适用的地方)patches/:按目标组织的补丁文件

飞行前检查

在每个升级会话开始时运行一次: 清除 rerere 缓存(如果启用):git rerere clear在电子和..回购协议。先前尝试中记录的陈旧解决方案可能会默默地应用错误的合并。确保安装了预提交挂钩:检查.git/hooks/pre-commit存在。如果没有,请运行yarn husky安装它。钩子运行lint-staged它处理 C++ 文件的 clang 格式。

工作流程

运行e sync --3(该--3标志启用 3 路合并,始终需要)如果成功 → 跳到步骤 5 如果补丁失败:从错误输出中识别目标存储库和补丁 分析失败(请参阅引用/patch-analysis.md)

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@electron · 未声明许可证
上下文用量评级
中等消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Electron Chromium Upgrade: Phase One

## Summary

Run `e sync --3` repeatedly, fixing patch conflicts as they arise, until it succeeds. Then export patches and commit changes atomically.

## Success Criteria

**Linter Requirements**:
- Code/patch edits: Title must be exactly `{CL-Number}: {upstream CL original title}` with `Ref: {URL}` in the body.
- Metadata-only patch updates (hashes/line numbers): Message must be exactly `chore: update patches` with no body.

Phase One is complete when:
- `e sync --3` exits with code 0 (no patch failures)
- All changes are committed per the commit guidelines

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.

**CRITICAL** Never use `git am --skip` and then manually recreate a patch by making a new commit. This destroys the original patch's authorship, commit message, and position in the series. If `git am --continue` reports "No changes", investigate why — the changes were likely absorbed by a prior conflict resolution's 3-way merge. Present this situation to the user rather than skipping and recreating.

## 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

## Pre-flight Checks

Run these once at the start of each upgrade session:

1. **Clear rerere cache** (if enabled): `git rerere clear` in both the electron and `..` repos. Stale recorded resolutions from a prior attempt can silently apply wrong merges.
2. **Ensure pre-commit hooks are installed**: Check that `.git/hooks/pre-commit` exists. If not, run `yarn husky` to install it. The hook runs `lint-staged` which handles clang-format for C++ files.

## Workflow

1. Run `e sync --3` (the `--3` flag enables 3-way merge, always required)
2. If succeeds → skip to step 5
3. 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
4. When `e sync --3` succeeds, run `e patches all`
5. **Read `references/phase-one-commit-guidelines.md` NOW**, then commit changes following those instructions exactly.

## 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 {target} --commit-updates` | Export patches and auto-commit trivial changes |
| `e patches --list-targets` | List targets and config paths |

## Patch System Mental Model

```
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.

## Patch Fixing Rules

1. **Preserve authorship**: Keep original author in TODO comments (from patch `From:` field)
2. **Never change TODO assignees**: `TODO(name)` must retain original name
3. **Update descriptions**: If upstream changed (e.g., `DCHECK` → `CHECK_IS_TEST`), update patch commit message to reflect current state
4. **Never skip-and-recreate a patch**: If `git am --continue` says "No changes — did you forget to use 'git add'?", do NOT run `git am --skip` and create a replacement commit. The patch's changes were already absorbed by a prior 3-way merge resolution. This means an earlier conflict resolution pulled in too many changes. Present the situation to the user for guidance — the correct fix may require re-doing an earlier resolution more carefully to keep each patch's changes separate.

# Electron Chromium Upgrade: Phase Two

## Summary

Run `e build -k 999 -- --quiet` 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.

## Success Criteria

**Linter Requirements**:
- Code/patch edits: Title must be exactly `{CL-Number}: {upstream CL original title}` with `Ref: {URL}` in the body.
- Metadata-only patch updates (hashes/line numbers): Message must be exactly `chore: update patches` with no body.

Phase Two is complete when:
- `e build -k 999 -- --quiet` 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

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.

## 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)

## Workflow

1. Run `e build -k 999 -- --quiet` (the `--quiet` flag suppresses per-target status lines, showing only errors and the final result)
2. If succeeds → skip to step 6
3. 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
4. **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 patches"`
5. Return to step 1
6. When `e build` succeeds, run `e start --version`
7. 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

## Commands Reference

| Command | Purpose |
|---------|---------|
| `e build -k 999 -- --quiet` | Build Electron, continue on errors, suppress status lines |
| `e build -t {target}.o` | Build just one specific target to verify a fix |
| `e start --version` | Validate Electron launches after successful build |

## Two Types of Build Fixes

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

When the error is in a file that Electron patches (check with `grep -l "filename" patches/chromium/*.patch`):

1. Edit the file in the Chromium source tree (e.g., `/src/chrome/browser/...`)
2. 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>^
    ```
3. Export the updated patch: `e patches chromium`
4. Commit the updated patch file following `references/phase-one-commit-guidelines.md`.

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:

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

# 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`

# 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.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。