Skip to content

Commit d23df03

Browse files
Trottgibfahn
Trott
authored and
gibfahn
committed
doc: prepare for v8/V8 linting in doc text
PR-URL: #17163 Backport-PR-URL: #17765 Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Alexey Orlenko <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]>
1 parent fcb8b91 commit d23df03

12 files changed

+40
-18
lines changed

‎doc/api/all.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
<!--lint disable prohibited-strings-->
12
@include documentation
23
@include synopsis
34
@include assert

‎doc/api/process.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1403,9 +1403,9 @@ tarball.
14031403
* `lts` {string} a string label identifying the [LTS][] label for this release.
14041404
This property only exists for LTS releases and is `undefined` for all other
14051405
release types, including _Current_ releases. Currently the valid values are:
1406-
- `'Argon'` for the v4.x LTS line beginning with v4.2.0.
1407-
- `'Boron'` for the v6.x LTS line beginning with v6.9.0.
1408-
- `'Carbon'` for the v8.x LTS line beginning with v8.9.1.
1406+
- `'Argon'` for the 4.x LTS line beginning with 4.2.0.
1407+
- `'Boron'` for the 6.x LTS line beginning with 6.9.0.
1408+
- `'Carbon'` for the 8.x LTS line beginning with 8.9.1.
14091409

14101410
For example:
14111411

‎doc/changelogs/CHANGELOG_ARCHIVE.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Node.js ChangeLog Archive
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th>v0.11</th>

‎doc/changelogs/CHANGELOG_IOJS.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# io.js ChangeLog
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th>v3</th>

‎doc/changelogs/CHANGELOG_V010.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Node.js 0.10 ChangeLog
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th colspan="2">Stable</th>

‎doc/changelogs/CHANGELOG_V012.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Node.js 0.12 ChangeLog
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th>Stable</th>

‎doc/changelogs/CHANGELOG_V4.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Node.js 4 ChangeLog
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th>LTS 'Argon'</th>

‎doc/changelogs/CHANGELOG_V5.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Node.js 5 ChangeLog
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th>Stable</th>

‎doc/changelogs/CHANGELOG_V6.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Node.js 6 ChangeLog
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th>LTS 'Boron'</th>

‎doc/changelogs/CHANGELOG_V7.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Node.js 7 ChangeLog
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th title="Previously called 'Stable'">Current</th>

‎doc/changelogs/CHANGELOG_V8.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Node.js 8 ChangeLog
22

3+
<!--lint disable prohibited-strings-->
4+
35
<table>
46
<tr>
57
<th>LTS 'Carbon'</th>

‎doc/guides/maintaining-V8.md

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -181,15 +181,15 @@ to be cherry-picked in the Node.js repository and V8-CI must test the change.
181181

182182
* For each abandoned V8 branch corresponding to an LTS branch that is affected by the bug:
183183
* Open a cherry-pick PR on nodejs/node targeting the appropriate *vY.x-staging* branch (e.g. *v6.x-staging* to fix an issue in V8-5.1).
184-
* Increase the patch level version in v8-version.h. This will not cause any problems with versioning because V8 will not publish other patches for this branch, so Node.js can effectively bump the patch version.
184+
* Increase the patch level version in `v8-version.h`. This will not cause any problems with versioning because V8 will not publish other patches for this branch, so Node.js can effectively bump the patch version.
185185
* In some cases the patch may require extra effort to merge in case V8 has changed substantially. For important issues we may be able to lean on the V8 team to get help with reimplementing the patch.
186186
* Run the Node.js [V8-CI](https://ci.nodejs.org/job/node-test-commit-v8-linux/) in addition to the [Node.js CI](https://ci.nodejs.org/job/node-test-pull-request/).
187187

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

194194
* Download and apply the commit linked-to in the issue (in this case a51f429). `curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 --directory=deps/v8`. If the branches have diverged significantly, this may not apply cleanly. It may help to try to cherry-pick the merge to the oldest branch that was done upstream in V8. In this example, this would be the patch from the merge to 5.2. The hope is that this would be closer to the V8 5.1, and has a better chance of applying cleanly. If you're stuck, feel free to ping @ofrobots for help.
195195
* Modify the commit message to match the format we use for V8 backports and replace yourself as the author. `git commit --amend --reset-author`. You may want to add extra description if necessary to indicate the impact of the fix on Node.js. In this case the original issue was descriptive enough. Example:
@@ -287,7 +287,7 @@ To audit for floating patches:
287287
git log --oneline deps/v8
288288
```
289289

290-
To replace the copy of V8 in Node.js, use the '[update-v8](https://gist.github.com/targos/8da405e96e98fdff01a395bed365b816)' script<sup>2</sup>. For example, if you want to replace the copy of V8 in Node.js with the branch-head for V8 5.1 branch:
290+
To replace the copy of V8 in Node.js, use the `[update-v8](https://gist.github.com/targos/8da405e96e98fdff01a395bed365b816)` script<sup>2</sup>. For example, if you want to replace the copy of V8 in Node.js with the branch-head for V8 5.1 branch:
291291

292292
```shell
293293
cd $NODE_DIR
@@ -304,20 +304,23 @@ This should be followed up with manual refloating of all relevant patches.
304304

305305
The fact that Node.js keeps a vendored, potentially edited copy of V8 in deps/
306306
makes the above processes a bit complicated. An alternative proposal would be to
307-
create a fork of V8 at nodejs/v8 that would be used to maintain the V8 branches.
308-
This has several benefits:
307+
create a fork of V8 at `nodejs/v8` that would be used to maintain the V8
308+
branches. This has several benefits:
309309

310-
* The process to update the version of V8 in Node.js could be automated to track the tips of various V8 branches in nodejs/v8.
311-
* It would simplify cherry-picking and porting of fixes between branches as the version bumps in v8-version.h would happen as part of this update instead of on every change.
310+
* The process to update the version of V8 in Node.js could be automated to track
311+
the tips of various V8 branches in `nodejs/v8`.
312+
* It would simplify cherry-picking and porting of fixes between branches as the version bumps in `v8-version.h` would happen as part of this update instead of on every change.
312313
* It would simplify the V8-CI and make it more automatable.
313-
* The history of the V8 branch in nodejs/v8 becomes purer and it would make it easier to pull in the V8 team for help with reviewing.
314+
* The history of the V8 branch in `nodejs/v8` becomes purer and it would make it
315+
easier to pull in the V8 team for help with reviewing.
314316
* It would make it simpler to setup an automated build that tracks Node.js master + V8 lkgr integration build.
315317

316318
This would require some tooling to:
317319

318320
* A script that would update the V8 in a specific Node.js branch with V8 from upstream (dependent on branch abandoned vs. active).
319-
* We need a script to bump V8 version numbers when a new version of V8 is promoted from nodejs/v8 to nodejs/node.
320-
* Enabled the V8-CI build in Jenkins to build from the nodejs/v8 fork.
321+
* We need a script to bump V8 version numbers when a new version of V8 is
322+
promoted from `nodejs/v8` to `nodejs/node`.
323+
* Enabled the V8-CI build in Jenkins to build from the `nodejs/v8` fork.
321324

322325
## Proposal: Dealing with the need to float patches to a stable/beta
323326

@@ -342,4 +345,4 @@ up working, we will investigate making this change upstream.
342345

343346
<sup>1</sup>Node.js 0.12 and older are intentionally omitted from this document as their support is ending soon.
344347

345-
<sup>2</sup>It seems that @targos is working on port of this script here https://github.com/targos/update-v8.
348+
<sup>2</sup>@targos is working on [a port of this script](https://github.com/targos/update-v8).

0 commit comments

Comments
 (0)