From 5bb58998a8f03f275a65f3a4a2dee53b095b7860 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 Backport-PR-URL: https://github.com/nodejs/node/pull/17765 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/guides/maintaining-V8.md | 33 ++++++++++++++++------------- 12 files changed, 40 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 42d2dd63c8b783..3a209d98e6e1dd 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -1403,9 +1403,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 02320672d63128..578f69292837a6 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 dce5f4c14a98a2..602982f4bfcac7 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 767798009f6203..3efbbd7b9d9cf0 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 2c80814c4fd9c6..1b67db58708b89 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 e64e7c04834975..608b8f802f276b 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 3deb6adf09473f..1ced8522440b82 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 00437b6247a3a1..a5b7faca278cd4 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 6a621bf5285d1b..fb959b947c40a5 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 82354ee7e7a8b1..2da709f6a5db3f 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/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 8683cd4f12086b..8a0d47494d5235 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -181,15 +181,15 @@ 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). - * 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. + * 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. * 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: @@ -287,7 +287,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 @@ -304,20 +304,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 @@ -342,4 +345,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).
LTS 'Carbon'