From bee142150130d60e96857124c6cea109bcf21433 Mon Sep 17 00:00:00 2001 From: Daijiro Wachi Date: Sun, 28 May 2017 22:20:21 +0200 Subject: [PATCH] doc: fix doc styles BUILDING.md + L122: Missing code-language flag + L170: Strong should use `*` as a marker doc/changelogs/CHANGELOG_V6.md + L1494: Don't pad `emphasis` with inner spaces doc/guides/maintaining-V8.md + L3: Don't use multiple top level headings + L16: Don't use multiple top level headings + L40: Don't use multiple top level headings + L124: Don't use multiple top level headings + L182: Missing code-language flag + L223: Don't use multiple top level headings + L288: Don't use multiple top level headings + L307: Don't use multiple top level headings doc/guides/writing-tests.md + L322: Missing code-language flag + L329: Missing code-language flag doc/releases.md + L299: Missing code-language flag PR-URL: https://github.com/nodejs/node/pull/13270 Reviewed-By: Luigi Pinca Reviewed-By: Alexey Orlenko Reviewed-By: Michael Dawson --- BUILDING.md | 4 ++-- doc/changelogs/CHANGELOG_V6.md | 2 +- doc/guides/maintaining-V8.md | 32 ++++++++++++++++---------------- doc/guides/writing-tests.md | 4 ++-- doc/releases.md | 2 +- 5 files changed, 22 insertions(+), 22 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 5cac93621c1523..427034b84a9b96 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -119,7 +119,7 @@ and not a newer version. To run the tests: -``` +```console $ make test ``` @@ -167,7 +167,7 @@ Prerequisites: including the Community edition (remember to select "Common Tools for Visual C++ 2015" feature during installation). * [Visual Studio 2017](https://www.visualstudio.com/downloads/), any edition (including the Build Tools SKU). - __Required Components:__ "MSbuild", "VC++ 2017 v141 toolset" and one of the Windows SDKs (10 or 8.1). + **Required Components:** "MSbuild", "VC++ 2017 v141 toolset" and one of the Windows SDKs (10 or 8.1). * Basic Unix tools required for some tests, [Git for Windows](http://git-scm.com/download/win) includes Git Bash and tools which can be included in the global `PATH`. diff --git a/doc/changelogs/CHANGELOG_V6.md b/doc/changelogs/CHANGELOG_V6.md index 0b4d6b0d215167..00437b6247a3a1 100644 --- a/doc/changelogs/CHANGELOG_V6.md +++ b/doc/changelogs/CHANGELOG_V6.md @@ -1492,7 +1492,7 @@ This is also a security release. All Node.js users should consult the security r * [[`86b9db601d`](https://github.com/nodejs/node/commit/86b9db601d)] - **src**: add missing length argument to send comment (Daniel Bevenius) [#8816](https://github.com/nodejs/node/pull/8816) * [[`aa11205f71`](https://github.com/nodejs/node/commit/aa11205f71)] - **src**: rename CHECK_NOT_OOB() macro (Ben Noordhuis) [#8784](https://github.com/nodejs/node/pull/8784) * [[`8be818eb07`](https://github.com/nodejs/node/commit/8be818eb07)] - **src**: fix minor typo in comments (Daniel Bevenius) [#8736](https://github.com/nodejs/node/pull/8736) -* [[`41ad6e3965`](https://github.com/nodejs/node/commit/41ad6e3965)] - **src**: rename handle__ to handle_ in HandleWrap (Daniel Bevenius) [#8712](https://github.com/nodejs/node/pull/8712) +* [[`41ad6e3965`](https://github.com/nodejs/node/commit/41ad6e3965)] - **src**: rename `handle__` to `handle_` in HandleWrap (Daniel Bevenius) [#8712](https://github.com/nodejs/node/pull/8712) * [[`9205edc35c`](https://github.com/nodejs/node/commit/9205edc35c)] - **src**: don't abort when c-ares initialization fails (Ben Noordhuis) [#8710](https://github.com/nodejs/node/pull/8710) * [[`6ddfe89fdf`](https://github.com/nodejs/node/commit/6ddfe89fdf)] - **src**: remove VS 2013 compatibility hacks (Ben Noordhuis) [#8067](https://github.com/nodejs/node/pull/8067) * [[`a9491f1604`](https://github.com/nodejs/node/commit/a9491f1604)] - **src**: make ReqWrap req_ member private (Daniel Bevenius) [#8532](https://github.com/nodejs/node/pull/8532) diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index e57b73bcf91d3a..e917ca439c9001 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -1,6 +1,6 @@ # Maintaining V8 in Node.js -# Background +## Background V8 follows the Chromium release schedule. The support horizon for Chromium is very different from the support horizon that Node.js needs to provide to its @@ -13,7 +13,7 @@ This document attempts to document the current processes and proposes a workflow for maintaining the V8 branches in Node.js LTS and Current releases and how the Node.js and V8 teams at Google can help. -# V8 Release Schedule +## V8 Release Schedule V8 and Chromium follow a [roughly 6-week release cadence](https://www.chromium.org/developers/calendar). At any given time there are three V8 branches that are **active**. @@ -26,7 +26,7 @@ For example, at the time of this writing: All older branches are considered **abandoned**, and are not maintained by the V8 team. -## V8 merge process overview +### V8 merge process overview The process for backporting bug fixes to active branches is officially documented [on the V8 wiki](https://github.com/v8/v8/wiki/Merging%20&%20Patching). The summary of the process is: @@ -37,7 +37,7 @@ The process for backporting bug fixes to active branches is officially documente * Merge requests to an abandoned branch will be rejected. * Only bug fixes are accepted for backporting. -# Node.js Support Requirements +## Node.js Support Requirements At any given time Node.js needs to be maintaining a few different V8 branches for the various Current, LTS, and nightly releases. At present this list @@ -121,7 +121,7 @@ The versions of V8 used in Node.js v4.x and v6.x have already been abandoned by upstream V8. However, Node.js needs to continue supporting these branches for many months (Current branches) or several years (LTS branches). -# Maintenance Process +## Maintenance Process Once a bug in Node.js has been identified to be caused by V8, the first step is to identify the versions of Node.js and V8 affected. The bug may be present in @@ -134,7 +134,7 @@ process. * Backporting to abandoned branches. * Backports identified by the V8 team. Bugs identified by upstream V8 that we haven't encountered in Node.js yet. -## Unfixed Upstream Bugs +### Unfixed Upstream Bugs If the bug can be reproduced on the [`vee-eight-lkgr` branch](https://github.com/v8/node/tree/vee-eight-lkgr), Chromium canary, or V8 tip-of-tree, and the test case is valid, then the bug needs to be fixed upstream first. @@ -144,7 +144,7 @@ If the bug can be reproduced on the [`vee-eight-lkgr` branch](https://github.com * V8's build waterfall tests your change. * Once the bug is fixed it may still need backporting, if it exists in other V8 branches that are still active or are branches that Node.js cares about. Follow the process for backporting below. -## Backporting to Active Branches +### Backporting to Active Branches If the bug exists in any of the active V8 branches, we may need to get the fix backported. At any given time there are [two active branches](https://build.chromium.org/p/client.v8.branches/console) (beta and stable) in addition to master. The following steps are needed to backport the fix: @@ -160,7 +160,7 @@ If the bug exists in any of the active V8 branches, we may need to get the fix b * It is possible that the merge request may not get approved, for example if it is considered to be a feature or otherwise too risky for V8 stable. In such cases we float the patch on the Node.js side. See the process on 'Backporting to Abandoned branches'. * Once the fix has been merged upstream, it can be picked up during an update of the V8 branch, (see below). -## Backporting to Abandoned Branches +### Backporting to Abandoned Branches Abandoned V8 branches are supported in the Node.js V8 repository. The fix needs to be cherry-picked in the Node.js repository and V8-CI must test the change. @@ -179,7 +179,7 @@ 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: -``` +```console deps: cherry-pick a51f429 from V8 upstream Original commit message: @@ -200,7 +200,7 @@ PR-URL: ``` * Open a PR against the `v6.x-staging` branch in the Node.js repo. Launch the normal and [V8-CI](https://ci.nodejs.org/job/node-test-commit-v8-linux/) 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. -## Backports Identified by the V8 team +### Backports Identified by the V8 team For bugs found through the browser or other channels, the V8 team marks bugs that might be applicable to the abandoned branches in use by Node.js. This is @@ -220,13 +220,13 @@ to shepherd through the backport process. External contributors are welcome to collaborate on the backport process as well. Note that some of the bugs may be security issues and will not be visible to external collaborators. -# Updating V8 +## Updating V8 Node.js keeps a vendored copy of V8 inside of deps/ directory. In addition Node.js may need to float patches that do not exist upstream. This means that some care may need to be taken to update the vendored copy of V8. -## Minor updates (patch level) +### Minor updates (patch level) Because there may be floating patches on the version of V8 in Node.js, it is safest to apply the patch level updates as a patch. For example, imagine that @@ -254,7 +254,7 @@ 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. -## Major Updates +### Major Updates We upgrade the version of V8 in Node.js master whenever a V8 release goes stable upstream, that is, whenever a new release of Chrome comes out. @@ -285,7 +285,7 @@ them once you have reviewed them. This should be followed up with manual refloating of all relevant patches. -# Proposal: Using a fork repo to track upstream V8 +## Proposal: Using a fork repo to track upstream V8 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 @@ -304,7 +304,7 @@ This would require some tooling to: * 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 +## Proposal: Dealing with the need to float patches to a stable/beta Sometimes upstream V8 may not want to merge a fix to their stable branches, but we might. An example of this would be a fix for a performance regression that @@ -323,7 +323,7 @@ We are trying this out in https://github.com/nodejs/node/pull/9754. If this ends up working, we will investigate making this change upstream. -## Notes +### Notes 1Node.js 0.12 and older are intentionally omitted from this document as their support is ending soon. diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index 4d15f73ae8395e..b9e614dc256ac0 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -319,14 +319,14 @@ static void at_exit_callback(void* arg) { ``` Next add the test to the `sources` in the `cctest` target in node.gyp: -``` +```console 'sources': [ 'test/cctest/test_env.cc', ... ], ``` The test can be executed by running the `cctest` target: -``` +```console $ make cctest ``` diff --git a/doc/releases.md b/doc/releases.md index eafc906026d6b5..f1f82fdb9816bb 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -296,7 +296,7 @@ Create a new blog post by running the [nodejs.org release-post.js script](https: * The links to the download files won't be complete unless you waited for the ARMv6 builds. Any downloads that are missing will have `*Coming soon*` next to them. It's your responsibility to manually update these later when you have the outstanding builds. * The SHASUMS256.txt.asc content is at the bottom of the post. When you update the list of tarballs you'll need to copy/paste the new contents of this file to reflect those changes. * Always use pull-requests on the nodejs.org repo. Be respectful of that working group, but you shouldn't have to wait for PR sign-off. Opening a PR and merging it immediately _should_ be fine. However, please follow the following commit message format: -``` +```console Blog: vX.Y.Z release post Refs: