Patches in Electron

Patches in Electron

Electron is built on two major upstream projects: Chromium and Node.js. Each of these projects has several of their own dependencies, too. We try our best to use these dependencies exactly as they are but sometimes we can't achieve our goals without patching those upstream dependencies to fit our use cases.

Every patch in Electron is a maintenance burden. When upstream code changes, patches can break—sometimes without even a patch conflict or a compilation error. It's an ongoing effort to keep our patch set up-to-date and effective. So we strive to keep our patch count at a minimum. To that end, every patch must describe its reason for existence in its commit message. That reason must be one of the following:

The patch is temporary, and is intended to be (or has been) committed upstream or otherwise eventually removed. Include a link to an upstream PR or code review if available, or a procedure for verifying whether the patch is still needed at a later date.

The patch allows the code to compile in the Electron environment, but cannot be upstreamed because it's Electron-specific (e.g. patching out references to Chrome's <code>Profile</code>). Include reasoning about why the change cannot be implemented without a patch (e.g. by subclassing or copying the code).

The patch makes Electron-specific changes in functionality which are fundamentally incompatible with upstream.

In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches.

If you find yourself in the unfortunate position of having to make a change which can only be made through patching an upstream project, you'll need to know how to manage patches in Electron.

All patches to upstream projects in Electron are contained in the <code>patches/</code> directory. Each subdirectory of <code>patches/</code> contains several patch files, along with a <code>.patches</code> file which lists the order in which the patches should be applied. Think of these files as making up a series of git commits that are applied on top of the upstream project after we check it out.

复制

To help manage these patch sets, we provide two tools: <code>git-import-patches</code> and <code>git-export-patches</code>. <code>git-import-patches</code> imports a set of patch files into a git repository by applying each patch in the correct order and creating a commit for each one. <code>git-export-patches</code>does the reverse; it exports a series of git commits in a repository into a set of files in a directory and an accompanying <code>.patches</code> file.

Side note: the reason we use a <code>.patches</code> file to maintain the order of applied patches, rather than prepending a number like <code>001-</code>to each file, is because it reduces conflicts related to patch ordering. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.

NOTE: <code>git-export-patches</code> ignores any uncommitted files, so you must create a commit if you want your changes to be exported. The subject line of the commit message will be used to derive the patch file name, and the body of the commit message should include the reason for the patch's existence.

Re-exporting patches will sometimes cause shasums in unrelated patches to change. This is generally harmless and can be ignored (but go ahead and add those changes to your PR, it'll stop them from showing up for other people).

Note that <code>git-import-patches</code> will mark the commit that was <code>HEAD</code> when it was run as <code>refs/patches/upstream-head</code>. This lets you keep track of which commits are from Electron patches (those that come after <code>refs/patches/upstream-head</code>) and which commits are in upstream (those before <code>refs/patches/upstream-head</code>).

When updating an upstream dependency, patches may fail to apply cleanly. Often, the conflict can be resolved automatically by git with a 3-way merge. You can instruct <code>git-import-patches</code> to use the 3-way merge algorithm by passing the <code>-3</code> argument:

If <code>git-import-patches -3</code> encounters a merge conflict that it can't resolve automatically, it will pause and allow you to resolve the conflict manually. Once you have resolved the conflict, <code>git add</code> the resolved files and continue to apply the rest of the patches by running <code>git am --continue</code>.