From 911f16329e1aa58fa52592a132c7072c3b5a3a19 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 18 Nov 2017 19:46:33 -0800 Subject: [PATCH] doc: prepare for v8/V8 linting in doc text MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/17163 Reviewed-By: Michaël Zasso Reviewed-By: Vse Mozhet Byt Reviewed-By: Benjamin Gruenbaum Reviewed-By: Alexey Orlenko Reviewed-By: Colin Ihrig Reviewed-By: James M Snell Reviewed-By: Gireesh Punathil --- doc/api/all.md | 1 + doc/api/process.md | 6 +++--- doc/changelogs/CHANGELOG_ARCHIVE.md | 2 ++ doc/changelogs/CHANGELOG_IOJS.md | 2 ++ doc/changelogs/CHANGELOG_V010.md | 2 ++ doc/changelogs/CHANGELOG_V012.md | 2 ++ doc/changelogs/CHANGELOG_V4.md | 2 ++ doc/changelogs/CHANGELOG_V5.md | 2 ++ doc/changelogs/CHANGELOG_V6.md | 2 ++ doc/changelogs/CHANGELOG_V7.md | 2 ++ doc/changelogs/CHANGELOG_V8.md | 2 ++ doc/changelogs/CHANGELOG_V9.md | 2 ++ doc/guides/maintaining-V8.md | 33 ++++++++++++++++------------- 13 files changed, 42 insertions(+), 18 deletions(-) diff --git a/doc/api/all.md b/doc/api/all.md index b11661d2b7e916..d013f07bd328fc 100644 --- a/doc/api/all.md +++ b/doc/api/all.md @@ -1,3 +1,4 @@ + @include documentation @include synopsis @include assert diff --git a/doc/api/process.md b/doc/api/process.md index 01dc630869dd7a..178928c8b6a321 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -1459,9 +1459,9 @@ tarball. * `lts` {string} a string label identifying the [LTS][] label for this release. This property only exists for LTS releases and is `undefined` for all other release types, including _Current_ releases. Currently the valid values are: - - `'Argon'` for the v4.x LTS line beginning with v4.2.0. - - `'Boron'` for the v6.x LTS line beginning with v6.9.0. - - `'Carbon'` for the v8.x LTS line beginning with v8.9.1. + - `'Argon'` for the 4.x LTS line beginning with 4.2.0. + - `'Boron'` for the 6.x LTS line beginning with 6.9.0. + - `'Carbon'` for the 8.x LTS line beginning with 8.9.1. For example: diff --git a/doc/changelogs/CHANGELOG_ARCHIVE.md b/doc/changelogs/CHANGELOG_ARCHIVE.md index ba1f385a7cfaa9..35d879064f0283 100644 --- a/doc/changelogs/CHANGELOG_ARCHIVE.md +++ b/doc/changelogs/CHANGELOG_ARCHIVE.md @@ -1,5 +1,7 @@ # Node.js ChangeLog Archive + + diff --git a/doc/changelogs/CHANGELOG_IOJS.md b/doc/changelogs/CHANGELOG_IOJS.md index 76f6fef8f64206..c419c534cac398 100644 --- a/doc/changelogs/CHANGELOG_IOJS.md +++ b/doc/changelogs/CHANGELOG_IOJS.md @@ -1,5 +1,7 @@ # io.js ChangeLog + +
v0.11
diff --git a/doc/changelogs/CHANGELOG_V010.md b/doc/changelogs/CHANGELOG_V010.md index ed9a7fe9bed12a..d9ad08acf0f8ba 100644 --- a/doc/changelogs/CHANGELOG_V010.md +++ b/doc/changelogs/CHANGELOG_V010.md @@ -1,5 +1,7 @@ # Node.js 0.10 ChangeLog + +
v3
diff --git a/doc/changelogs/CHANGELOG_V012.md b/doc/changelogs/CHANGELOG_V012.md index 93a65abf5084a7..a57773269814ee 100644 --- a/doc/changelogs/CHANGELOG_V012.md +++ b/doc/changelogs/CHANGELOG_V012.md @@ -1,5 +1,7 @@ # Node.js 0.12 ChangeLog + +
Stable
diff --git a/doc/changelogs/CHANGELOG_V4.md b/doc/changelogs/CHANGELOG_V4.md index e8e6fbff2e9aee..64c5150f5ef1ac 100644 --- a/doc/changelogs/CHANGELOG_V4.md +++ b/doc/changelogs/CHANGELOG_V4.md @@ -1,5 +1,7 @@ # Node.js 4 ChangeLog + +
Stable
diff --git a/doc/changelogs/CHANGELOG_V5.md b/doc/changelogs/CHANGELOG_V5.md index 198b7a71d6a099..4f223e62f79b73 100644 --- a/doc/changelogs/CHANGELOG_V5.md +++ b/doc/changelogs/CHANGELOG_V5.md @@ -1,5 +1,7 @@ # Node.js 5 ChangeLog + +
LTS 'Argon'
diff --git a/doc/changelogs/CHANGELOG_V6.md b/doc/changelogs/CHANGELOG_V6.md index 9d9972d377f4a3..1757680cc5c4c0 100644 --- a/doc/changelogs/CHANGELOG_V6.md +++ b/doc/changelogs/CHANGELOG_V6.md @@ -1,5 +1,7 @@ # Node.js 6 ChangeLog + +
Stable
diff --git a/doc/changelogs/CHANGELOG_V7.md b/doc/changelogs/CHANGELOG_V7.md index 4c0a81cd36dbc4..dd9fa4d269a8d6 100644 --- a/doc/changelogs/CHANGELOG_V7.md +++ b/doc/changelogs/CHANGELOG_V7.md @@ -1,5 +1,7 @@ # Node.js 7 ChangeLog + +
LTS 'Boron'
diff --git a/doc/changelogs/CHANGELOG_V8.md b/doc/changelogs/CHANGELOG_V8.md index 6c626c36ea63f4..83e024b4fc29c3 100644 --- a/doc/changelogs/CHANGELOG_V8.md +++ b/doc/changelogs/CHANGELOG_V8.md @@ -1,5 +1,7 @@ # Node.js 8 ChangeLog + +
Current
diff --git a/doc/changelogs/CHANGELOG_V9.md b/doc/changelogs/CHANGELOG_V9.md index ffe6c1d33ccbc8..c8c5c1845e617f 100644 --- a/doc/changelogs/CHANGELOG_V9.md +++ b/doc/changelogs/CHANGELOG_V9.md @@ -1,5 +1,7 @@ # Node.js 9 ChangeLog + +
LTS 'Carbon'
diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 350ecd0c72f61e..f101f95edc6928 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -181,16 +181,16 @@ to be cherry-picked in the Node.js repository and V8-CI must test the change. * For each abandoned V8 branch corresponding to an LTS branch that is affected by the bug: * 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). - * On Node.js < 9.0.0: 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. + * On Node.js < 9.0.0: 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. * On Node.js >= 9.0.0: Increase the `v8_embedder_string` number in `common.gypi`. * 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. * 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/). -An example for workflow how to cherry-pick consider the following bug: -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 cherry-picked. To cherry-pick, here's an -example workflow: +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: * 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. * 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: @@ -289,7 +289,7 @@ To audit for floating patches: git log --oneline deps/v8 ``` -To replace the copy of V8 in Node.js, use the '[update-v8](https://gist.github.com/targos/8da405e96e98fdff01a395bed365b816)' script2. For example, if you want to replace the copy of V8 in Node.js with the branch-head for V8 5.1 branch: +To replace the copy of V8 in Node.js, use the `[update-v8](https://gist.github.com/targos/8da405e96e98fdff01a395bed365b816)` script2. For example, if you want to replace the copy of V8 in Node.js with the branch-head for V8 5.1 branch: ```shell cd $NODE_DIR @@ -306,20 +306,23 @@ This should be followed up with manual refloating of all relevant patches. The fact that Node.js keeps a vendored, potentially edited copy of V8 in deps/ makes the above processes a bit complicated. An alternative proposal would be to -create a fork of V8 at nodejs/v8 that would be used to maintain the V8 branches. -This has several benefits: +create a fork of V8 at `nodejs/v8` that would be used to maintain the V8 +branches. This has several benefits: -* 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. -* 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. +* 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`. +* 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. * It would simplify the V8-CI and make it more automatable. -* 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. +* 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. * It would make it simpler to setup an automated build that tracks Node.js master + V8 lkgr integration build. This would require some tooling to: * A script that would update the V8 in a specific Node.js branch with V8 from upstream (dependent on branch abandoned vs. active). -* We need a script to bump V8 version numbers when a new version of V8 is promoted from nodejs/v8 to nodejs/node. -* Enabled the V8-CI build in Jenkins to build from the nodejs/v8 fork. +* We need a script to bump V8 version numbers when a new version of V8 is + promoted from `nodejs/v8` to `nodejs/node`. +* Enabled the V8-CI build in Jenkins to build from the `nodejs/v8` fork. ## Proposal: Dealing with the need to float patches to a stable/beta @@ -344,4 +347,4 @@ up working, we will investigate making this change upstream. 1Node.js 0.12 and older are intentionally omitted from this document as their support is ending soon. -2It seems that @targos is working on port of this script here https://github.com/targos/update-v8. +2@targos is working on [a port of this script](https://github.com/targos/update-v8).
Current