diff --git a/docs/development/README.md b/docs/development/README.md index c5fa6292e482..81775f7b0af8 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -23,4 +23,3 @@ For guides on Electron app development, see * [Debugging on macOS](debugging-instructions-macos.md) * [Setting Up Symbol Server in Debugger](setting-up-symbol-server.md) * [Patches](patches.md) -* [Upgrading Node](upgrading-node.md) diff --git a/docs/development/upgrading-node.md b/docs/development/upgrading-node.md deleted file mode 100644 index 7b5dca06ba0b..000000000000 --- a/docs/development/upgrading-node.md +++ /dev/null @@ -1,121 +0,0 @@ -# Upgrading Node - -## Discussion - -Chromium and Node.js both depend on V8, and Electron contains -only a single copy of V8, so it's important to ensure that the -version of V8 chosen is compatible with the build's version of -Node.js and Chromium. - -Upgrading Node is much easier than upgrading Chromium, so fewer -conflicts arise if one upgrades Chromium first, then chooses the -upstream Node release whose version of V8 is closest to the one -Chromium contains. - -Electron has its own [Node fork](https://github.com/electron/node) -with modifications for the V8 build details mentioned above -and for exposing API needed by Electron. Once an upstream Node -release is chosen, it's placed in a branch in Electron's Node fork -and any Electron Node patches are applied there. - -Another factor is that the Node project patches its version of V8. -As mentioned above, Electron builds everything with a single copy -of V8, so Node's V8 patches must be ported to that copy. - -Once all of Electron's dependencies are building and using the same -copy of V8, the next step is to fix any Electron code issues caused -by the Node upgrade. - -[FIXME] something about a Node debugger in Atom that we (e.g. deepak) -use and need to confirm doesn't break with the Node upgrade? - -So in short, the primary steps are: - -1. Update Electron's Node fork to the desired version -2. Backport Node's V8 patches to our copy of V8 -3. Update the GN build files, porting changes from node's GYP files -4. Update Electron's DEPS to use new version of Node - -## Updating Electron's Node [fork](https://github.com/electron/node) - -1. Ensure that `master` on `electron/node` has updated release tags from `nodejs/node` -2. Create a branch in https://github.com/electron/node: `electron-node-vX.X.X` where the base that you're branching from is the tag for the desired update - - `vX.X.X` Must use a version of Node compatible with our current version of Chromium -3. Re-apply our commits from the previous version of Node we were using (`vY.Y.Y`) to `v.X.X.X` - - Check release tag and select the range of commits we need to re-apply - - Cherry-pick commit range: - 1. Checkout both `vY.Y.Y` & `v.X.X.X` - 2. `git cherry-pick FIRST_COMMIT_HASH..LAST_COMMIT_HASH` - - Resolve merge conflicts in each file encountered, then: - 1. `git add ` - 2. `git cherry-pick --continue` - 3. Repeat until finished - - -## Updating [V8](https://github.com/electron/node/src/V8) Patches - -We need to generate a patch file from each patch that Node -applies to V8. - -```sh -$ cd third_party/electron_node -$ CURRENT_NODE_VERSION=vX.Y.Z -# Find the last commit with the message "deps: update V8 to " -# This commit corresponds to Node resetting V8 to its pristine upstream -# state at the stated version. -$ LAST_V8_UPDATE="$(git log --grep='^deps: update V8' --format='%H' -1 deps/v8)" -# This creates a patch file containing all changes in deps/v8 from -# $LAST_V8_UPDATE up to the current Node version, formatted in a way that -# it will apply cleanly to the V8 repository (i.e. with `deps/v8` -# stripped off the path and excluding the v8/gypfiles directory, which -# isn't present in V8. -$ git format-patch \ - --relative=deps/v8 \ - $LAST_V8_UPDATE..$CURRENT_NODE_VERSION \ - deps/v8 \ - ':(exclude)deps/v8/gypfiles' \ - --stdout \ - > ../../electron/common/patches/v8/node_v8_patches.patch -``` - -This list of patches will probably include one that claims to -make the V8 API backwards-compatible with a previous version of -V8. Unfortunately, those patches almost always change the V8 API -in a way that is incompatible with Chromium. - -It's usually easier to update Node to work without the -compatibility patch than to update Chromium to work with the -compatibility patch, so it's recommended to revert the -compatibility patch and fix any errors that arise when compiling -Node. - -## Update Electron's `DEPS` file - -Update the `DEPS` file in the root of -[electron/electron](https://github.com/electron/electron) to -point to the git hash of the updated Node. - -## Notes - -- Node maintains its own fork of V8 - - They backport a small amount of things as needed - - Documentation in Node about how [they work with V8](https://nodejs.org/api/v8.html) -- We update code such that we only use one copy of V8 across all of Electron - - E.g Electron, Chromium, and Node.js -- We don’t track upstream closely due to logistics: - - Upstream uses multiple repos and so merging into a single repo - would result in lost history. So we only update when we’re planning - a Node version bump in Electron. -- Chromium is large and time-consuming to update, so we typically - choose the Node version based on which of its releases has a version - of V8 that’s closest to the version in Chromium that we’re using. - - We sometimes have to wait for the next periodic Node release - because it will sync more closely with the version of V8 in the new Chromium - - Electron keeps all its patches in the repo because it’s simpler than - maintaining different repos for patches for each upstream project. - - Crashpad, Node.js, Chromium, Skia etc. patches are all kept in the same place - - Building Node: - - We maintain our own GN build files for Node.js to make it easier to ensure - that eevrything is built with the same compiler flags. - This means that every time we upgrade Node.js we have to do a modest amount of - work to synchronize the GN files with the upstream GYP files.