Skip to content

Commit

Permalink
doc: fix doc styles
Browse files Browse the repository at this point in the history
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: #13270
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Alexey Orlenko <eaglexrlnk@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
  • Loading branch information
watilde authored and jasnell committed Jun 5, 2017
1 parent cc6ec2f commit bee1421
Show file tree
Hide file tree
Showing 5 changed files with 22 additions and 22 deletions.
4 changes: 2 additions & 2 deletions BUILDING.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ and not a newer version.

To run the tests:

```
```console
$ make test
```

Expand Down Expand Up @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion doc/changelogs/CHANGELOG_V6.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
32 changes: 16 additions & 16 deletions doc/guides/maintaining-V8.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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**.

Expand All @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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:

Expand All @@ -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.
Expand All @@ -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:
Expand All @@ -200,7 +200,7 @@ PR-URL: <pr link>
```
* 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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.

<!-- Footnotes themselves at the bottom. -->
## Notes
### Notes

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

Expand Down
4 changes: 2 additions & 2 deletions doc/guides/writing-tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
2 changes: 1 addition & 1 deletion doc/releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: <full URL to your release proposal PR>
Expand Down

0 comments on commit bee1421

Please sign in to comment.