From f8858a7577dccb652bf5249d938d3c6ad4aa8bf4 Mon Sep 17 00:00:00 2001 From: Charles Kerr Date: Thu, 23 Nov 2017 10:12:31 +0100 Subject: [PATCH 1/5] 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 0000000000..c0fc929171 --- /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 0000000000..ddf9db6bbe --- /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` + + + + + + + + + + + + + From f91020a04d13fe15a42e1c5d0b787661f186c893 Mon Sep 17 00:00:00 2001 From: Charles Kerr Date: Thu, 23 Nov 2017 12:48:43 +0100 Subject: [PATCH 2/5] add section for updating submodule references --- docs/development/upgrading-node.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/development/upgrading-node.md b/docs/development/upgrading-node.md index ddf9db6bbe..0a7ca8ad01 100644 --- a/docs/development/upgrading-node.md +++ b/docs/development/upgrading-node.md @@ -103,6 +103,23 @@ We need to generate a patch file from each patch applied to V8. - Update `patches/v8/README.md` =FIXME== (In libchromiumcontent repo) Read `patches/v8/README.md` to see which patchfiles +- Update Electron's submodule references: + ```sh + cd electron/vendor/node + electron/vendor/node$ git fetch + electron/vendor/node$ git checkout electron-node-vA.B.C + electron/vendor/node$ cd ../libchromiumcontent + electron/vendor/libchromiumcontent$ git fetch + electron/vendor/libchromiumcontent$ git checkout upgrade-to-chromium-X + electron/vendor/libchromiumcontent$ cd ../.. + electron$ git add vendor + electron$ git commit -m "update submodule referefences for node and libc" + electron$ git pso upgrade-to-chromium-62 + electron$ script/bootstrap.py -d + electron$ script/build.py -c -D + ``` + + ## Notes From 178462b800fe6a471bee699c4df9f935e8bc5723 Mon Sep 17 00:00:00 2001 From: Shelley Vohr Date: Fri, 24 Nov 2017 10:35:57 +0100 Subject: [PATCH 3/5] chrome -> chromium and updates to crashpad doc --- ...rading-chrome.md => upgrading-chromium.md} | 2 +- docs/development/upgrading-crashpad.md | 56 ++++++++++--------- docs/development/upgrading-node.md | 2 +- 3 files changed, 33 insertions(+), 27 deletions(-) rename docs/development/{upgrading-chrome.md => upgrading-chromium.md} (99%) diff --git a/docs/development/upgrading-chrome.md b/docs/development/upgrading-chromium.md similarity index 99% rename from docs/development/upgrading-chrome.md rename to docs/development/upgrading-chromium.md index 07e137b97f..6257a030d6 100644 --- a/docs/development/upgrading-chrome.md +++ b/docs/development/upgrading-chromium.md @@ -1,4 +1,4 @@ -# Upgrading Chromium Workflow +# Upgrading Chromium This document is meant to serve as an overview of what steps are needed on each Chromium upgrade in Electron. diff --git a/docs/development/upgrading-crashpad.md b/docs/development/upgrading-crashpad.md index c0fc929171..0eb31a8f59 100644 --- a/docs/development/upgrading-crashpad.md +++ b/docs/development/upgrading-crashpad.md @@ -1,36 +1,42 @@ -- 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` +# Upgrading Crashpad + +1. 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 + - We need to check out the correponding branch. + - Clone Google's crashpad (https://chromium.googlesource.com/crashpad/crashpad) + - `git clone https://chromium.googlesource.com/crashpad/crashpad` + - Check out the branch with the revision checksum: + - `git checkout ` + - Add electron's crashpad fork as a remote + - `git remote add electron https://github.com/electron/crashpad` + - Check out a new branch for the update + - `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` +2. Make a checklist of the Electron patches that need to be applied + with `git log --oneline` + - Or view http://github.com/electron/crashpad/commits/previous-branch-name -- Update Electron to build the new crashpad: +3. For each patch: + - In `electron-crashpad-vA.B.C.D`, cherry-pick the patch's checksum + - `git cherry-pick ` + - Resolve any conflicts + - Make sure it builds then add, commit, and push work to electron's crashpad fork + - `git push electron electron-crashpad-vA.B.C.D` + +4. 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` +5. Regenerate Ninja files against both targets + - 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` + - Both should build with no errors +6. 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 index 0a7ca8ad01..4e81e1fa96 100644 --- a/docs/development/upgrading-node.md +++ b/docs/development/upgrading-node.md @@ -119,7 +119,7 @@ We need to generate a patch file from each patch applied to V8. electron$ script/build.py -c -D ``` - + ## Notes From ba6224039c8bdd55e543aca0b469c8a37220c9c3 Mon Sep 17 00:00:00 2001 From: Shelley Vohr Date: Fri, 24 Nov 2017 11:06:04 +0100 Subject: [PATCH 4/5] make some things more explicit and style conformity --- docs/development/upgrading-chromium.md | 129 +++++++++---------------- 1 file changed, 47 insertions(+), 82 deletions(-) diff --git a/docs/development/upgrading-chromium.md b/docs/development/upgrading-chromium.md index 6257a030d6..b7a08c7053 100644 --- a/docs/development/upgrading-chromium.md +++ b/docs/development/upgrading-chromium.md @@ -12,43 +12,38 @@ on each Chromium upgrade in Electron. ## Upgrade `libcc` to a new Chromium -### Steps -### 1. Get the code and initialize the project: -```sh -$ git clone git@github.com:electron/libchromiumcontent.git -$ cd libchromiumcontent -$ ./script/bootstrap -v -``` -### 2. Find the new beta/stable Chromium version from [OmahaProxy](https://omahaproxy.appspot.com/). -### 3. Put it into the `libchromiumcontent/VERSION` file, then run `$ ./script/update` - - It will probably fail applying patches. -### 4. Fix `*.patch` files in the `/patches` and `/patches-mas` folders. -### 5. (Optional) Run a separate script to apply patches (`script/update` uses it internally): - ```sh - $ ./script/apply-patches - ``` - - There is also another script `/script/patch.py` that could be more useful, check `--help` to learn how it works with `$ ./script/patch.py -h` -### 6. Run the build when all patches can be applied without errors - ```sh - $ ./script/build - ``` - - If some patches are no longer compatible with the Chromium code, fix compilation errors. -### 7. When build succeeds, create a `dist` for Electron - `$ ./script/create-dist --no_zip` - - It will create `dist/main` folder in the root of the libcc repo, you will need it to build Electron. -### 8. (Optional) Update script contents if there are errors resultant of some files being removed or renamed. (`--no_zip` prevents script from create `dist` archives, you don't need them.) +1. Get the code and initialize the project: + - ```sh + $ git clone git@github.com:electron/libchromiumcontent.git + $ cd libchromiumcontent + $ ./script/bootstrap -v``` +2. Find the new beta/stable Chromium version from [OmahaProxy](https://omahaproxy.appspot.com/). +3. Put it into the `libchromiumcontent/VERSION` file, then run `$ ./script/update` + - It will probably fail applying patches. +4. Fix `*.patch` files in the `/patches` and `/patches-mas` folders. +5. (Optional) Run a separate script to apply patches (`script/update` uses it internally): + - `$ ./script/apply-patches` + - There is also another script `/script/patch.py` that could be more useful + - Check `--help` to learn how it works with `$ ./script/patch.py -h` +6. Run the build when all patches can be applied without errors + - `$ ./script/build` + - If some patches are no longer compatible with the Chromium code, fix compilation errors. +7. When build succeeds, create a `dist` for Electron + - `$ ./script/create-dist --no_zip` + - It will create `dist/main` folder in the root of the libcc repo + - You will need it to build Electron. +8. (Optional) Update script contents if there are errors resultant of some files being removed or renamed. (`--no_zip` prevents script from create `dist` archives, you don't need them.) ## Update Electron Code -### Steps -### 1. Get the code: -```sh -$ git clone git@github.com:electron/electron.git -$ cd electron -``` -### 2. If you already have libcc built on you machine in its own repo, you need to tell Electron explicitly to use it: - ```sh +1. Get the code: + - ```sh + $ git clone git@github.com:electron/electron.git + $ cd electron + ``` +2. If you already have libcc built on you machine in its own repo, you need to tell Electron explicitly to use it: + - ```sh $ ./script/bootstrap.py -v \ --libcc_source_path /src \ --libcc_shared_library_path /shared_library \ @@ -58,19 +53,21 @@ $ cd electron `$ ./script/bootstrap.py -v` - Ensure that libcc submodule (`vendor/libchromiumcontent`) points to a right revision -### 3. Set CLANG_REVISION in` script/update-clang.sh` to match the version Chromium is using. -- Located in `electron/libchromiumcontent/src/tools/clang/scripts/update.py` +3. Set CLANG_REVISION in` script/update-clang.sh` to match the version Chromium is using. + - Located in `electron/libchromiumcontent/src/tools/clang/scripts/update.py` -### 4. Checkout Chromium if you haven't already: https://chromium.googlesource.com/chromium/src.git/+/{VERSION}/tools/clang/scripts/update.py - - (Replace the `{VERSION}` placeholder in the url above to the Chromium version libcc uses.) -### 5. Build Electron. -- Try to build Debug version first: `$ ./script/build.py -c D` -- You will need it to run tests -### 6. Fix compilation and linking errors -### 7. Ensure that Release build can be built too: `$ ./script/build.py -c R` +4. Checkout Chromium if you haven't already: + - https://chromium.googlesource.com/chromium/src.git/+/{VERSION}/tools/clang/scripts/update.py + - (Replace the `{VERSION}` placeholder in the url above to the Chromium version libcc uses.) +5. Build Electron. + - Try to build Debug version first: `$ ./script/build.py -c D` + - You will need it to run tests +6. Fix compilation and linking errors +7. Ensure that Release build can be built too + - `$ ./script/build.py -c R` - Often the Release build will have different linking errors that you'll need to fix. - Some compilation and linking errors are caused by missing source/object files in the libcc `dist` -### 8. Update `./script/create-dist` in the libcc repo, recreate a `dist`, and run Electron bootstrap script once again. +8. Update `./script/create-dist` in the libcc repo, recreate a `dist`, and run Electron bootstrap script once again. ### Tips for fixing compilation errors - Fix build config errors first @@ -87,54 +84,22 @@ Fix the failing tests. Follow all the steps above to fix Electron code on all supported platforms. -## Update Crashpad +## Updating Crashpad -- Electron's crashpad fork: https://github.com/electron/crashpad -- Primary crashpad repo: https://chromium.googlesource.com/crashpad/crashpad/ +If there are any compilation errors related to the Crashpad, it probably means you need to update the fork to a newer revision: see [Upgrading Crashpad](https://github.com/electron/electron/tree/master/docs/development/upgrading-crashpad.md) for instructions on how to do that. -### Steps -If there are any compilation errors related to the Crashpad, it probably means you need to update the fork to a newer revision: +## Updating NodeJS -### 1. Clone Electron's fork of the Crashpad, add the main repo as another remote: - ```sh - $ git clone https://github.com/electron/crashpad && cd crashpad - $ git remote add upstream https://chromium.googlesource.com/crashpad/crashpad/ && git fetch upstream - ``` -### 2. Find a revision Chromium uses in src/third_party/crashpad/README.chromium -### 3. Rebase the master branch to that REVISION - ```sh - $ git rebase REVISION - ``` - - If there are nontrivial conflicts during rebase, consult with the commit's author. -### 4. Add a tag with the next Electron version to a top commit in the master branch - - e.g. if current Electron version is `1.11.*`, then use tag `electron-1.12.0`, because it will be used in the next version. -### 5. Ensure Electron-specific commits in the master branch on GitHub are properly tagged - - If they aren't, force push will make them orphans and they'll be lost. -### 6. Force push to Electron's crashpad fork. -### 7. Update `/vendor/crashpad` submodule in the Electron's upgrade branch to point to the updated crashpad. +Upgrade `vendor/node` to the Node release that corresponds to the v8 version being used in the new Chromium release. See the v8 versions in Node on - -## Update NodeJS - -- Upgrade `vendor/node` to the Node release that corresponds to the v8 version - being used in the new Chromium release. See the v8 versions in Node on - https://nodejs.org/en/download/releases for more details. - - You can find v8 version Chromium is using on [OmahaProxy](http://omahaproxy.appspot.com). - If it's not available check `v8/include/v8-version.h` - in the Chromium checkout. +See [Upgrading Node](https://github.com/electron/electron/tree/master/docs/development/upgrading-node.md) for instructions on how to do this. ## Verify ffmpeg Support -Electron ships with a version of `ffmpeg` that includes proprietary codecs by -default. A version without these codecs is built and distributed with each -release as well. Each Chrome upgrade should verify that switching this version is -still supported. +Electron ships with a version of `ffmpeg` that includes proprietary codecs by default. A version without these codecs is built and distributed with each release as well. Each Chrome upgrade should verify that switching this version is still supported. -You can verify Electron's support for multiple `ffmpeg` builds by loading the -following page. It should work with the default `ffmpeg` library distributed -with Electron and not work with the `ffmpeg` library built without proprietary -codecs. +You can verify Electron's support for multiple `ffmpeg` builds by loading the following page. It should work with the default `ffmpeg` library distributed with Electron and not work with the `ffmpeg` library built without proprietary codecs. ```html From bd70ec5e97fbbc843a919351194faae71cb72266 Mon Sep 17 00:00:00 2001 From: Shelley Vohr Date: Fri, 24 Nov 2017 11:15:07 +0100 Subject: [PATCH 5/5] finalize node upgrade doc --- docs/development/upgrading-node.md | 45 +++++++++++++++--------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/development/upgrading-node.md b/docs/development/upgrading-node.md index 4e81e1fa96..0424cedfc5 100644 --- a/docs/development/upgrading-node.md +++ b/docs/development/upgrading-node.md @@ -36,7 +36,7 @@ So in short, the primary steps are: * Update submodules * Update Node.js build configuration -## Updating [Electron's Node fork](https://github.com/electron/node) +## 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 @@ -55,56 +55,57 @@ So in short, the primary steps are: 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 +1. Get a copy of Electron's libcc fork + - `$ git clone https://github.com/electron/libchromiumcontent` +2. Run `script/update` to get the latest libcc - This will be time-consuming -- Remove our copies of the old Node v8 patches +3. 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 +4. 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 +5. 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` +6. Read `patches/v8/README.md` to see which patchfiles came from the previous version of V8 and therefore need to be removed. + - Delete each patchfile referenced in `patches/v8/README.md` +7. For each patch, do: + - (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) + - (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 + - Ensure that local status is clean: `git status` to make sure there are no unstaged changes. + - 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: + - 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: + - 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: + - 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: + - 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: + - 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: + - (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 - -- Update Electron's submodule references: - ```sh +8. Update `patches/v8/README.md` with references to all new patches that have been added so that the next person will know which need to be removed. +9. Update Electron's submodule references: + - ```sh cd electron/vendor/node electron/vendor/node$ git fetch electron/vendor/node$ git checkout electron-node-vA.B.C