Electron 中的补丁

Electron 构建于两个主要的上游项目之上：Chromium 和 Node.js。这两个项目本身也有几个依赖项。我们尽最大努力完全按照它们的方式使用这些依赖项，但有时为了适应我们的用例，必须修补这些上游依赖项才能实现我们的目标。

补丁理由

Electron 中的每一个补丁都是维护的负担。当上游代码更改时，补丁可能会失效——有时甚至不会出现补丁冲突或编译错误。保持我们的补丁集最新且有效是一项持续的工作。因此，我们努力将补丁数量保持在最低限度。为此，每个补丁必须在其提交消息中描述其存在的原因。该原因必须是以下之一：

该补丁是临时的，旨在（或已经）提交到上游或最终移除。如果有可用的上游 PR 或代码评审链接，或者用于验证补丁在稍后日期是否仍然需要的程序，请包含在内。
此补丁允许代码在 Electron 环境中编译，但不能向上游提交，因为它特定于 Electron (例如，修补掉对 Chrome 的 Profile 的引用)。请包含为什么不能在没有补丁的情况下实现此更改的理由 (例如，通过子类化或复制代码)。
该补丁对功能进行了特定于 Electron 的更改，而这些更改与上游根本不兼容。

总的来说，我们合作的所有上游项目都很友好，并且通常乐于接受允许相关代码与 Electron 和上游项目都兼容的重构。(例如参阅 Chromium 中的此变更，这使得我们可以移除一个做了相同事情的补丁；或者 Node 中的此变更，这对 Node 没有影响但修复了 Electron 中的一个错误)。 我们应尽可能地将变更向上游推送，并避免无限期存在的补丁。

补丁系统

如果您发现自己不幸需要对上游项目进行只能通过打补丁来完成的更改，您需要知道如何在 Electron 中管理补丁。

Electron 中对上游项目的所有补丁都包含在 patches/ 目录中。 patches/ 的每个子目录都包含多个补丁文件，以及一个 .patches 文件，其中列出了应应用补丁的顺序。可以将这些文件视为构成一系列 git 提交，这些提交在我们检出上游项目后应用在其之上。

patches
├── config.json   <-- this describes which patchset directory is applied to what project
├── chromium
│   ├── .patches
│   ├── accelerator.patch
│   ├── add_contentgpuclient_precreatemessageloop_callback.patch
│   ⋮
├── node
│   ├── .patches
│   ├── add_openssl_is_boringssl_guard_to_oaep_hash_check.patch
│   ├── build_add_gn_build_files.patch
│   ⋮
⋮

为了帮助管理这些补丁集，我们提供了两个工具：git-import-patches 和 git-export-patches。 git-import-patches 通过按正确顺序应用每个补丁并为每个补丁创建一个提交，将一组补丁文件导入到 git 仓库中。 git-export-patches 执行相反的操作；它将仓库中的一系列 git 提交导出到目录中的一组文件和一个相应的 .patches 文件中。

旁注：我们使用 .patches 文件来维护应用补丁的顺序，而不是在每个文件前加上一个数字（例如 001-），是因为它减少了与补丁排序相关的冲突。这可以防止两个 PR 都以相同的编号在系列末尾添加一个补丁，最终都被合并导致重复标识符的情况，并且当在系列中间添加或删除补丁时，它也减少了变动。

使用方法

添加新补丁

$ cd src/third_party/electron_node
$ vim some/code/file.cc
$ git commit
$ ../../electron/script/git-export-patches -o ../../electron/patches/node

注意: git-export-patches 会忽略任何未提交的文件，因此如果您希望导出更改，必须创建一个提交。提交消息的主题行将用于派生补丁文件名，提交消息的正文应包含补丁存在的原因。

重新导出补丁有时会导致不相关补丁中的 shasums 发生变化。这通常是无害的，可以忽略 (但请继续将这些更改添加到您的 PR 中，这将阻止它们出现在其他人面前)。

编辑现有补丁

$ cd src/v8
$ vim some/code/file.cc
$ git log
# Find the commit sha of the patch you want to edit.
$ git commit --fixup [COMMIT_SHA]
$ git rebase --autosquash -i [COMMIT_SHA]^
$ ../electron/script/git-export-patches -o ../electron/patches/v8

请注意，符号 ^ 在 Windows 上可能会导致问题。解决方法是将其引用起来 "[COMMIT_SHA]^" 或避免使用它 [COMMIT_SHA]~1。

移除补丁

$ vim src/electron/patches/node/.patches
# Delete the line with the name of the patch you want to remove
$ cd src/third_party/electron_node
$ git reset --hard refs/patches/upstream-head
$ ../../electron/script/git-import-patches ../../electron/patches/node
$ ../../electron/script/git-export-patches -o ../../electron/patches/node

请注意，git-import-patches 在运行时会将当时的 HEAD 提交标记为 refs/patches/upstream-head。这让您可以跟踪哪些提交来自 Electron 补丁（在 refs/patches/upstream-head 之后的那些），哪些提交在上游（在 refs/patches/upstream-head 之前的那些）。

解决冲突

更新上游依赖项时，补丁可能无法干净地应用。通常，冲突可以通过 git 使用三方合并自动解决。您可以通过传递 -3 参数来指示 git-import-patches 使用三方合并算法：

$ cd src/third_party/electron_node
# If the patch application failed midway through, you can reset it with:
$ git am --abort
# And then retry with 3-way merge:
$ ../../electron/script/git-import-patches -3 ../../electron/patches/node

如果 git-import-patches -3 遇到无法自动解决的合并冲突，它将暂停并允许您手动解决冲突。解决冲突后，使用 git add 添加已解决的文件，然后运行 git am --continue 继续应用其余补丁。

补丁理由​

补丁系统​

使用方法​

添加新补丁​

编辑现有补丁​

移除补丁​

解决冲突​