@@ -208,6 +208,58 @@ backport the fix:
208
208
Abandoned V8 branches are supported in the Node.js repository. The fix needs
209
209
to be cherry-picked in the Node.js repository and V8-CI must test the change.
210
210
211
+ As an example for how to backport changes, consider the bug [ RegExp show
212
+ inconsistent result with other browsers] ( https://crbug.com/v8/5199 ) . From the
213
+ bug we can see that it was merged by V8 into 5.2 and 5.3, and not into V8 5.1
214
+ (since it was already abandoned). Since Node.js ` v6.x ` uses V8 5.1, the fix
215
+ needed to be backported.
216
+
217
+ #### Backporting with ` git-node ` (recommended)
218
+
219
+ You can use [ ` git-node ` ] [ ] to help you backport patches. This removes
220
+ some manual steps and is recommended.
221
+
222
+ Here are the steps for the bug mentioned above:
223
+
224
+ 1 . Install ` git-node ` by installing [ ` node-core-utils ` ] [ ] .
225
+ 2 . Install the prerequisites for [ ` git-node-v8 ` ] [ ] .
226
+ 3 . Find the commit hash linked-to in the issue (in this case a51f429).
227
+ 4 . Checkout a branch off the appropriate _ vY.x-staging_ branch (e.g.
228
+ _ v6.x-staging_ to fix an issue in V8 5.1).
229
+ 5 . Run ` git node v8 backport a51f429 ` .
230
+ 6 . If there are conflicts, ` git-node ` will wait for you to resolve them.
231
+ ` git-node ` will prompt you to resolve them in another terminal and then
232
+ enter ` RESOLVED ` :
233
+ ``` console
234
+ $ git node v8 backport a51f429
235
+ ✔ Update local V8 clone
236
+ ❯ V8 commit backport
237
+ ✔ Get current V8 version
238
+ ✔ Generate patches
239
+ ❯ Apply and commit patches to deps/v8
240
+ ❯ Commit a51f429772d1
241
+ ⠏ Apply patch
242
+ ◼ Increment embedder version number
243
+ ◼ Commit patch
244
+
245
+ ? Resolve merge conflicts and enter 'RESOLVED' ‣
246
+ ```
247
+ 7 . After you resolve conflicts (or if there are no conflicts), the
248
+ output should look like this:
249
+ ``` console
250
+ $ git node v8 backport a51f429
251
+ ✔ Update local V8 clone
252
+ ✔ V8 commit backport
253
+ ```
254
+ 8 . Open a PR against the v6.x-staging branch in the Node.js repository.
255
+ Launch the normal and [ V8 CI] [ ] using the Node.js CI system. We only
256
+ needed to backport to v6.x as the other LTS branches weren't affected
257
+ by this bug.
258
+
259
+ See [ ` git-node-v8-backport ` ] [ ] for more documentation and additional options.
260
+
261
+ #### Backporting manually (not recommended)
262
+
211
263
* For each abandoned V8 branch corresponding to an LTS branch that is affected
212
264
by the bug:
213
265
* Checkout a branch off the appropriate _ vY.x-staging_ branch (e.g.
@@ -224,14 +276,7 @@ to be cherry-picked in the Node.js repository and V8-CI must test the change.
224
276
` tools/make-v8.sh ` to reconstruct a git tree in the ` deps/v8 ` directory to
225
277
run V8 tests.[ ^ 2 ]
226
278
227
- The [ ` git-node ` ] [ ] tool can be used to simplify this task. Run
228
- ` git node v8 backport <sha> ` to cherry-pick a commit.
229
-
230
- An example for workflow how to cherry-pick consider the bug
231
- [ RegExp show inconsistent result with other browsers] ( https://crbug.com/v8/5199 ) .
232
- From the bug we can see that it was merged by V8 into 5.2 and 5.3, and not into
233
- V8 5.1 (since it was already abandoned). Since Node.js ` v6.x ` uses V8 5.1, the
234
- fix needed to be cherry-picked. To cherry-pick, here's an example workflow:
279
+ Here are the steps for the bug mentioned above:
235
280
236
281
* Download and apply the commit linked-to in the issue (in this case a51f429):
237
282
@@ -322,6 +367,15 @@ compute the diff between these tags on the V8 repository, and then apply that
322
367
patch on the copy of V8 in Node.js. This should preserve the patches/backports
323
368
that Node.js may be floating (or else cause a merge conflict).
324
369
370
+ #### Applying minor updates with ` git-node ` (recommended)
371
+
372
+ 1 . Install [ ` git-node ` ] [ ] by installing [ ` node-core-utils ` ] [ ] .
373
+ 2 . Install the prerequisites for [ ` git-node-v8 ` ] [ ] .
374
+ 3 . Run ` git node v8 minor ` to apply a minor update.
375
+
376
+ See [ ` git-node-v8-minor ` ] [ ] for more documentation and additional options.
377
+
378
+ #### Applying minor updates manually (not recommended)
325
379
The rough outline of the process is:
326
380
327
381
``` bash
@@ -340,9 +394,6 @@ curl -L https://github.com/v8/v8/compare/${V8_OLD_VERSION}...${V8_NEW_VERSION}.p
340
394
V8 also keeps tags of the form _ 5.4-lkgr_ which point to the _ Last Known Good
341
395
Revision_ from the 5.4 branch that can be useful in the update process above.
342
396
343
- The [ ` git-node ` ] [ ] tool can be used to simplify this task. Run ` git node v8 minor `
344
- to apply a minor update.
345
-
346
397
### Major updates
347
398
348
399
We upgrade the version of V8 in Node.js ` main ` whenever a V8 release goes stable
@@ -427,4 +478,8 @@ This would require some tooling to:
427
478
[ V8MergingPatching ] : https://v8.dev/docs/merge-patch
428
479
[ V8TemplateMergeRequest ] : https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request
429
480
[ V8TemplateUpstreamBug ] : https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20upstream%20bug
481
+ [ `git-node-v8-backport` ] : https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-v8-backport-sha
482
+ [ `git-node-v8-minor` ] : https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-v8-minor
483
+ [ `git-node-v8` ] : https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md#git-node-v8
430
484
[ `git-node` ] : https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md#git-node-v8
485
+ [ `node-core-utils` ] : https://github.com/nodejs/node-core-utils#Install
0 commit comments