doc: recommend git-node-v8

kvakil · kvakil · commit 9cafec980ee8 · 2022-07-21T16:22:31.000Z
Per the comments in nodejs#43924, almost everyone uses `git-node-v8`. I included example steps for using `git-node-v8`.
diff --git a/doc/contributing/maintaining-V8.md b/doc/contributing/maintaining-V8.md
@@ -208,6 +208,53 @@ 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`. If the patch merges without any
+   conflicts, it will look like this:
+```console
+$ git node v8 backport a51f429
+&#10004; Update local V8 clone
+&#10004; V8 commit backport
+```
+6. If there are conflicts, `git-node` will wait for you to resolve them.
+   git-node` will prompt you to resolve them in another terminal and then
+   enter `RESOLVED`:
+```console
+$ git node v8 backport a51f429
+&#10004; Update local V8 clone
+&#10095; V8 commit backport
+  &#10004; Get current V8 version
+  &#10004; Generate patches
+  &#10095; Apply and commit patches to deps/v8
+    &#10095; Commit a51f429772d1
+      &#10255; Apply patch
+      &#9724; Increment embedder version number
+      &#9724; Commit patch
+
+? Resolve merge conflicts and enter 'RESOLVED' &#8227;
+```
+
+See [`git-node-v8-backport`][] for more documentation and additional options.
+
+#### Backporting manually (not recommended)
+
 * 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.
@@ -224,14 +271,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):
 
@@ -322,6 +362,15 @@ 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 (not recommended)
 The rough outline of the process is:
 
 ```bash
@@ -340,9 +389,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
@@ -427,4 +473,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
