Skip to content

Commit 85c517f

Browse files
committed
doc: recommend git-node-v8
Per the comments in nodejs#43924, almost everyone uses `git-node-v8`. I included example steps for using `git-node-v8`. I ran through both of these instructions on a clean Linux machine (I had to fudge the patch SHA of course) and they seemed to work. Refs: nodejs#43924
1 parent 2fd4c01 commit 85c517f

File tree

1 file changed

+71
-11
lines changed

1 file changed

+71
-11
lines changed

doc/contributing/maintaining-V8.md

Lines changed: 71 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,62 @@ backport the fix:
208208
Abandoned V8 branches are supported in the Node.js repository. The fix needs
209209
to be cherry-picked in the Node.js repository and V8-CI must test the change.
210210

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+
211267
* For each abandoned V8 branch corresponding to an LTS branch that is affected
212268
by the bug:
213269
* 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.
224280
`tools/make-v8.sh` to reconstruct a git tree in the `deps/v8` directory to
225281
run V8 tests.[^2]
226282

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:
235284

236285
* Download and apply the commit linked-to in the issue (in this case a51f429):
237286

@@ -322,6 +371,16 @@ compute the diff between these tags on the V8 repository, and then apply that
322371
patch on the copy of V8 in Node.js. This should preserve the patches/backports
323372
that Node.js may be floating (or else cause a merge conflict).
324373

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+
325384
The rough outline of the process is:
326385

327386
```bash
@@ -340,9 +399,6 @@ curl -L https://github.com/v8/v8/compare/${V8_OLD_VERSION}...${V8_NEW_VERSION}.p
340399
V8 also keeps tags of the form _5.4-lkgr_ which point to the _Last Known Good
341400
Revision_ from the 5.4 branch that can be useful in the update process above.
342401

343-
The [`git-node`][] tool can be used to simplify this task. Run `git node v8 minor`
344-
to apply a minor update.
345-
346402
### Major updates
347403

348404
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:
427483
[V8MergingPatching]: https://v8.dev/docs/merge-patch
428484
[V8TemplateMergeRequest]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request
429485
[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
430489
[`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

Comments
 (0)