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