@@ -208,6 +208,64 @@ 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
212
+ [ RegExp show inconsistent result with other browsers] ( https://crbug.com/v8/5199 ) .
213
+ From the bug we can see that it was merged by V8 into 5.2 and 5.3, and not into
214
+ V8 5.1 (since it was already abandoned). Since Node.js ` v6.x ` uses V8 5.1, the
215
+ fix 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
+
232
+ ``` console
233
+ $ git node v8 backport a51f429
234
+ ✔ Update local V8 clone
235
+ ❯ V8 commit backport
236
+ ✔ Get current V8 version
237
+ ✔ Generate patches
238
+ ❯ Apply and commit patches to deps/v8
239
+ ❯ Commit a51f429772d1
240
+ ⠏ Apply patch
241
+ ◼ Increment embedder version number
242
+ ◼ Commit patch
243
+
244
+ ? Resolve merge conflicts and enter 'RESOLVED' ‣
245
+ ```
246
+
247
+ Resolve conflicts, stage the files (you may need to open another terminal or use
248
+ a GUI git client), then return to the terminal running ` git-node ` , type
249
+ ` RESOLVED ` , and hit <kbd >Enter</kbd >.
250
+
251
+ 7 . After you resolve conflicts (or if there are no conflicts), the
252
+ output should look like this:
253
+
254
+ ``` console
255
+ $ git node v8 backport a51f429
256
+ ✔ Update local V8 clone
257
+ ✔ V8 commit backport
258
+ ```
259
+
260
+ 8 . Open a PR against the v6.x-staging branch in the Node.js repository.
261
+ Launch the normal and [ V8 CI] [ ] using the Node.js CI system. We only
262
+ needed to backport to v6.x as the other LTS branches weren't affected
263
+ by this bug.
264
+
265
+ See [ ` git-node-v8-backport ` ] [ ] for more documentation and additional options.
266
+
267
+ #### Backporting manually
268
+
211
269
* For each abandoned V8 branch corresponding to an LTS branch that is affected
212
270
by the bug:
213
271
* Checkout a branch off the appropriate _ vY.x-staging_ branch (e.g.
@@ -224,14 +282,7 @@ to be cherry-picked in the Node.js repository and V8-CI must test the change.
224
282
` tools/make-v8.sh ` to reconstruct a git tree in the ` deps/v8 ` directory to
225
283
run V8 tests.[ ^ 2 ]
226
284
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:
285
+ Here are the steps for the bug mentioned above:
235
286
236
287
* Download and apply the commit linked-to in the issue (in this case a51f429):
237
288
@@ -323,6 +374,16 @@ compute the diff between these tags on the V8 repository, and then apply that
323
374
patch on the copy of V8 in Node.js. This should preserve the patches/backports
324
375
that Node.js may be floating (or else cause a merge conflict).
325
376
377
+ #### Applying minor updates with ` git-node ` (recommended)
378
+
379
+ 1 . Install [ ` git-node ` ] [ ] by installing [ ` node-core-utils ` ] [ ] .
380
+ 2 . Install the prerequisites for [ ` git-node-v8 ` ] [ ] .
381
+ 3 . Run ` git node v8 minor ` to apply a minor update.
382
+
383
+ See [ ` git-node-v8-minor ` ] [ ] for more documentation and additional options.
384
+
385
+ #### Applying minor updates manually
386
+
326
387
The rough outline of the process is:
327
388
328
389
``` bash
@@ -341,9 +402,6 @@ curl -L https://github.com/v8/v8/compare/${V8_OLD_VERSION}...${V8_NEW_VERSION}.p
341
402
V8 also keeps tags of the form _ 5.4-lkgr_ which point to the _ Last Known Good
342
403
Revision_ from the 5.4 branch that can be useful in the update process above.
343
404
344
- The [ ` git-node ` ] [ ] tool can be used to simplify this task. Run ` git node v8 minor `
345
- to apply a minor update.
346
-
347
405
### Major updates
348
406
349
407
We upgrade the version of V8 in Node.js ` main ` whenever a V8 release goes stable
@@ -428,4 +486,8 @@ This would require some tooling to:
428
486
[ V8MergingPatching ] : https://v8.dev/docs/merge-patch
429
487
[ V8TemplateMergeRequest ] : https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request
430
488
[ V8TemplateUpstreamBug ] : https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20upstream%20bug
489
+ [ `git-node-v8-backport` ] : https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-v8-backport-sha
490
+ [ `git-node-v8-minor` ] : https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-v8-minor
491
+ [ `git-node-v8` ] : https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md#git-node-v8
431
492
[ `git-node` ] : https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md#git-node-v8
493
+ [ `node-core-utils` ] : https://github.com/nodejs/node-core-utils#Install
0 commit comments