From f8858a7577dccb652bf5249d938d3c6ad4aa8bf4 Mon Sep 17 00:00:00 2001 From: Charles Kerr Date: Thu, 23 Nov 2017 10:12:31 +0100 Subject: [PATCH] add rough draft of node, crashpad update notes --- docs/development/upgrading-crashpad.md | 36 +++++++ docs/development/upgrading-node.md | 142 +++++++++++++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 docs/development/upgrading-crashpad.md create mode 100644 docs/development/upgrading-node.md diff --git a/docs/development/upgrading-crashpad.md b/docs/development/upgrading-crashpad.md new file mode 100644 index 000000000000..c0fc92917154 --- /dev/null +++ b/docs/development/upgrading-crashpad.md @@ -0,0 +1,36 @@ +- Get the version of crashpad that we're going to use. + - `libcc/src/third_party/crashpad/README.chromium` will have a line `Revision:` with a checksum. + - clone [Electron's Crashpad fork](https://github.com/electron/crashpad) and create a new branch + - `git clone https://chromium.googlesource.com/crashpad/crashpad` + - `git checkout 01110c0a3b` + - `git remote add electron https://github.com/electron/crashpad` + - `git checkout -b electron-crashpad-vA.B.C.D` + - `A.B.C.D` is the Chromium version found in `libcc/VERSION` + and will be something like `62.0.3202.94` + +- Make a checklist of the Electron patches we need to apply + e.g. `git log --oneline` + or view http://github.com/electron/crashpad/commits/previous-branch-name +- Foreach patch: + - (in new branch) `git cherry-pick checksum` + - resolve any conflicts + - make sure it builds + - add && commit +- Push your work: + `git push electron electorn-crashpad-v62.0.3202.94` + +- Update Electron to build the new crashpad: + - `cd vendor/crashpad` + - `git fetch` + - `git checkout electron-crashpad-v62.0.3202.94` +- Regenerate Ninja files + - from Electron root's root, run `script/update.py` + - `script/build.py -c D --target=crashpad_client` + - `script/build.py -c D --target=crashpad_handler` + - If both of these work, it's probably good. +- Push changes to submodule reference + - (from electron root) `git add vendor/crashpad` + - `git push origin upgrade-to-chromium-62` + + + diff --git a/docs/development/upgrading-node.md b/docs/development/upgrading-node.md new file mode 100644 index 000000000000..ddf9db6bbedc --- /dev/null +++ b/docs/development/upgrading-node.md @@ -0,0 +1,142 @@ +# Upgrading Node + +## Discussion + +One upgrade issue is building all of Electron with a single copy +of V8 to ensure compatability. This is important because +upstream Node and [libchromiumcontent](upgrading-chrome.md) +both use their own versions of V8. + +Upgrading Node is much easier than upgrading libchromiumcontent, +so fewer conflicts arise if one upgrades libchromiumcontent first, +then chooses the upstream Node release whose V8 is closest to it. + +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 Electron to use new version of Node + * Update submodules + * Update Node.js build configuration + +## Updating [Electron's Node fork](https://github.com/electron/node) + +1. Create a branch in https://github.com/electron/node: `electron-node-vX.X.X` + - `vX.X.X` Must use a version of node compatible with our current version of chromium +2. 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 applied to V8. + +- Get a copy of Electron's libchromiumcontent fork +- Run `script/update` to get the latest libcc + - This will be time-consuming +- Remove our copies of the old Node v8 patches + - (In libchromiumcontent repo) Read `patches/v8/README.md` to see which patchfiles + were created during the last update + - Remove those files from `patches/v8/`: + - `git rm` the patchfiles + - edit `patches/v8/README.md` + - commit these removals +- Inspect Node [repo](https://github.com/electron/node) to see what patches upstream Node + used with their v8 after bumping its version + - `git log --oneline deps/V8` +- Create a checklist of the patches. This is useful for tracking your work and for + having a quick reference of commit hashes to use in the `git diff-tree` step below. +- For each patch, do: + 1. (In node repo) `git diff-tree --patch HASH > ~/path_to_libchromiumcontent/patches/v8/xxx-patch_name.patch` + - `xxx` is an incremented three-digit number (to force patch order) + - `patch_name` should loosely match the node commit messages, + e.g. `030-cherry_pick_cc55747,patch` if the Node commit message was "cherry-pick cc55747" + 2. (remainder of steps in libchromium repo) + Manually edit the `.patch` file to match upstream V8's directory: + - If a diff section has no instances of `deps/V8`, remove it altogether. + - We don’t want those patches because we’re only patching V8. + - Replace instances of `a/deps/v8`/filename.ext` with `a/filename.ext` + - This is needed because upstream Node keeps its V8 files in a subdirectory + 3. Ensure that local status is clean: `git status` to make sure there are no unstaged changes. + 4. Confirm that the patch applies cleanly with + `script/patch.py -r src/V8 -p patches/v8/xxx-patch_name.patch.patch` + 5. Create a new copy of the patch: + - `cd src/v8 && git diff > ../../test.patch && cd ../..` + - This is needed because the first patch has Node commit checksums that we don't want + 6. Confirm that checksums are the only difference between the two patches: + - `diff -u test.patch patches/v8/xxx-patch_name.patch` + 7. Replace the old patch with the new: + - `mv test.patch patches/v8/xxx-patch_name.patch` + 8. Add the patched code to the index _without_ committing: + - `cd src/v8 && git add . && cd ../..` + - We don't want to commit the changes (they're kept in the patchfiles) + but need them locally so that they don't show up in subsequent diffs + while we iterate through more patches + 9. Add the patch file to the index: + - `git add a patches/v8/` + 10. Optionally commit each patch file to ensure you can back up if you mess up a step: + - `git commit patches/v8/` +- Update `patches/v8/README.md` + =FIXME== (In libchromiumcontent repo) Read `patches/v8/README.md` to see which patchfiles + + +## Notes + +- libcc and V8 are treated as a single unit +- 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, libcc, and node +- 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. +- libcc 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 libcc 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 libcc + - Electron keeps all its patches in libcc because it’s simpler than + maintaining different repos for patches for each upstream project. + - Crashpad, node, libcc, etc. patches are all kept in the same place + - Building node: + - There’s a chance we need to change our build configuration + to match the build flags that node wants in `node/common.gypi` + + + + + + + + + + + + +