Skip to content

Commit

Permalink
doc: recommend git-node-v8
Browse files Browse the repository at this point in the history
Per the comments in #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: #43924

PR-URL: #43934
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Richard Lau <rlau@redhat.com>
  • Loading branch information
kvakil authored and danielleadams committed Jul 26, 2022
1 parent c95132e commit cb9b0e0
Showing 1 changed file with 73 additions and 11 deletions.
84 changes: 73 additions & 11 deletions doc/contributing/maintaining-V8.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,64 @@ backport the fix:
Abandoned V8 branches are supported in the Node.js repository. The fix needs
to be cherry-picked in the Node.js repository and V8-CI must test the change.

As an example for how to backport changes, consider the bug
[RegExp show inconsistent result with other browsers](https://crbug.com/v8/5199).
From the bug we can see that it was merged by V8 into 5.2 and 5.3, and not into
V8 5.1 (since it was already abandoned). Since Node.js `v6.x` uses V8 5.1, the
fix needed to be backported.

#### Backporting with `git-node` (recommended)

You can use [`git-node`][] to help you backport patches. This removes
some manual steps and is recommended.

Here are the steps for the bug mentioned above:

1. Install `git-node` by installing [`node-core-utils`][].
2. Install the prerequisites for [`git-node-v8`][].
3. Find the commit hash linked-to in the issue (in this case a51f429).
4. Checkout a branch off the appropriate _vY.x-staging_ branch (e.g.
_v6.x-staging_ to fix an issue in V8 5.1).
5. Run `git node v8 backport a51f429`.
6. If there are conflicts, `git-node` will wait for you to resolve them:

```console
$ git node v8 backport a51f429
✔ Update local V8 clone
V8 commit backport
✔ Get current V8 version
✔ Generate patches
❯ Apply and commit patches to deps/v8
❯ Commit a51f429772d1
⠏ Apply patch
◼ Increment embedder version number
◼ Commit patch

? Resolve merge conflicts and enter 'RESOLVED' ‣
```

Resolve conflicts, stage the files (you may need to open another terminal or use
a GUI git client), then return to the terminal running `git-node`, type
`RESOLVED`, and hit <kbd>Enter</kbd>.

7. After you resolve conflicts (or if there are no conflicts), the
output should look like this:

```console
$ git node v8 backport a51f429
✔ Update local V8 clone
✔ V8 commit backport
```

8. Open a PR against the v6.x-staging branch in the Node.js repository.
Launch the normal and [V8 CI][] using the Node.js CI system. We only
needed to backport to v6.x as the other LTS branches weren't affected
by this bug.

See [`git-node-v8-backport`][] for more documentation and additional options.

#### Backporting manually

* For each abandoned V8 branch corresponding to an LTS branch that is affected
by the bug:
* Checkout a branch off the appropriate _vY.x-staging_ branch (e.g.
Expand All @@ -224,14 +282,7 @@ to be cherry-picked in the Node.js repository and V8-CI must test the change.
`tools/make-v8.sh` to reconstruct a git tree in the `deps/v8` directory to
run V8 tests.[^2]

The [`git-node`][] tool can be used to simplify this task. Run
`git node v8 backport <sha>` to cherry-pick a commit.

An example for workflow how to cherry-pick consider the bug
[RegExp show inconsistent result with other browsers](https://crbug.com/v8/5199).
From the bug we can see that it was merged by V8 into 5.2 and 5.3, and not into
V8 5.1 (since it was already abandoned). Since Node.js `v6.x` uses V8 5.1, the
fix needed to be cherry-picked. To cherry-pick, here's an example workflow:
Here are the steps for the bug mentioned above:

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

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

#### Applying minor updates with `git-node` (recommended)

1. Install [`git-node`][] by installing [`node-core-utils`][].
2. Install the prerequisites for [`git-node-v8`][].
3. Run `git node v8 minor` to apply a minor update.

See [`git-node-v8-minor`][] for more documentation and additional options.

#### Applying minor updates manually

The rough outline of the process is:

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

The [`git-node`][] tool can be used to simplify this task. Run `git node v8 minor`
to apply a minor update.

### Major updates

We upgrade the version of V8 in Node.js `main` whenever a V8 release goes stable
Expand Down Expand Up @@ -428,4 +486,8 @@ This would require some tooling to:
[V8MergingPatching]: https://v8.dev/docs/merge-patch
[V8TemplateMergeRequest]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request
[V8TemplateUpstreamBug]: https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20upstream%20bug
[`git-node-v8-backport`]: https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-v8-backport-sha
[`git-node-v8-minor`]: https://github.com/nodejs/node-core-utils/blob/main/docs/git-node.md#git-node-v8-minor
[`git-node-v8`]: https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md#git-node-v8
[`git-node`]: https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md#git-node-v8
[`node-core-utils`]: https://github.com/nodejs/node-core-utils#Install

0 comments on commit cb9b0e0

Please # to comment.