v8.5.0 proposal

.eslintrc.yaml

@@ -10,6 +10,11 @@ env:
 parserOptions:
   ecmaVersion: 2017
 
+overrides:
+  - files: ["doc/api/esm.md", "*.mjs"]
+    parserOptions:
+      sourceType: module
+
 rules:
   # Possible Errors
   # http://eslint.org/docs/rules/#possible-errors

.gitignore

@@ -12,6 +12,7 @@
 !.gitignore
 !.gitkeep
 !.mailmap
+!.nycrc
 !.remarkrc
 
 core

.nycrc

@@ -0,0 +1,6 @@
+{
+  "exclude": [
+    "**/internal/process/write-coverage.js"
+  ],
+  "reporter": ["html", "text"]
+}

BUILDING.md

@@ -93,6 +93,8 @@ More Developer Tools...`. This step will install `clang`, `clang++`, and
 * You may want to setup [firewall rules](tools/macosx-firewall.sh)
 to avoid popups asking to accept incoming network connections when running tests:
 
+If the path to your build directory contains a space, the build will likely fail.
+
 ```console
 $ sudo ./tools/macosx-firewall.sh
 ```
@@ -126,6 +128,25 @@ To run the tests:
 $ make test
 ```
 
+To run the tests and generate code coverage reports:
+
+```console
+$ ./configure --coverage
+$ make coverage
+```
+
+This will generate coverage reports for both JavaScript and C++ tests (if you
+only want to run the JavaScript tests then you do not need to run the first
+command `./configure --coverage`).
+
+The `make coverage` command downloads some tools to the project root directory
+and overwrites the `lib/` directory. To clean up after generating the coverage
+reports:
+
+```console
+make coverage-clean
+```
+
 To build the documentation:
 
 This will build Node.js first (if necessary) and then use it to build the docs:
@@ -134,7 +155,7 @@ This will build Node.js first (if necessary) and then use it to build the docs:
 $ make doc
 ```
 
-If you have an existing Node.js you can build just the docs with:
+If you have an existing Node.js build, you can build just the docs with:
 
 ```console
 $ NODE=/path/to/node make doc-only
@@ -170,11 +191,14 @@ 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 at least one of the Windows SDKs.
+    *Note*: For "Windows 10 SDK (10.0.15063.0)" only the "Desktop C++ x86 and x64" flavor is required.
 * 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`.
 
+If the path to your build directory contains a space, the build will likely fail.
+
 ```console
 > .\vcbuild
 ```

CHANGELOG.md

@@ -27,7 +27,9 @@ release.
 </tr>
 <tr>
     <td valign="top">
-<b><a href="doc/changelogs/CHANGELOG_V8.md#8.3.0">8.3.0</a></b><br/>
+<b><a href="doc/changelogs/CHANGELOG_V8.md#8.5.0">8.5.0</a></b><br/>
+<a href="doc/changelogs/CHANGELOG_V8.md#8.4.0">8.4.0</a><br/>
+<a href="doc/changelogs/CHANGELOG_V8.md#8.3.0">8.3.0</a><br/>
 <a href="doc/changelogs/CHANGELOG_V8.md#8.2.1">8.2.1</a><br/>
 <a href="doc/changelogs/CHANGELOG_V8.md#8.2.0">8.2.0</a><br/>
 <a href="doc/changelogs/CHANGELOG_V8.md#8.1.4">8.1.4</a><br/>

COLLABORATOR_GUIDE.md

@@ -8,7 +8,7 @@
    - [Internal vs. Public API](#internal-vs-public-api)
    - [Breaking Changes](#breaking-changes)
    - [Deprecations](#deprecations)
-   - [Involving the CTC](#involving-the-ctc)
+   - [Involving the TSC](#involving-the-TSC)
 * [Landing Pull Requests](#landing-pull-requests)
    - [Technical HOWTO](#technical-howto)
    - [I Just Made a Mistake](#i-just-made-a-mistake)
@@ -30,7 +30,7 @@ pull requests to the Node.js project.
 Collaborators should feel free to take full responsibility for
 managing issues and pull requests they feel qualified to handle, as
 long as this is done while being mindful of these guidelines, the
-opinions of other Collaborators and guidance of the CTC.
+opinions of other Collaborators and guidance of the TSC.
 
 Collaborators may **close** any issue or pull request they believe is
 not relevant for the future of the Node.js project. Where this is
@@ -46,7 +46,7 @@ necessary.
 
 All modifications to the Node.js code and documentation should be
 performed via GitHub pull requests, including modifications by
-Collaborators and CTC members.
+Collaborators and TSC members.
 
 All pull requests must be reviewed and accepted by a Collaborator with
 sufficient expertise who is able to take full responsibility for the
@@ -70,16 +70,16 @@ For non-breaking changes, if there is no disagreement amongst
 Collaborators, a pull request may be landed given appropriate review.
 Where there is discussion amongst Collaborators, consensus should be
 sought if possible. The lack of consensus may indicate the need to
-elevate discussion to the CTC for resolution (see below).
+elevate discussion to the TSC for resolution (see below).
 
 Breaking changes (that is, pull requests that require an increase in
 the major version number, known as `semver-major` changes) must be
-elevated for review by the CTC. This does not necessarily mean that the
-PR must be put onto the CTC meeting agenda. If multiple CTC members
+elevated for review by the TSC. This does not necessarily mean that the
+PR must be put onto the TSC meeting agenda. If multiple TSC members
 approve (`LGTM`) the PR and no Collaborators oppose the PR, it can be
-landed. Where there is disagreement among CTC members or objections
+landed. Where there is disagreement among TSC members or objections
 from one or more Collaborators, `semver-major` pull requests should be
-put on the CTC meeting agenda.
+put on the TSC meeting agenda.
 
 All bugfixes require a test case which demonstrates the defect. The
 test should *fail* before the change, and *pass* after the change.
@@ -150,7 +150,7 @@ Exception to each of these points can be made if use or behavior of a given
 internal API can be demonstrated to be sufficiently relied upon by the Node.js
 ecosystem such that any changes would cause too much breakage. The threshold
 for what qualifies as "too much breakage" is to be decided on a case-by-case
-basis by the CTC.
+basis by the TSC.
 
 If it is determined that a currently undocumented object, property, method,
 argument, or event *should* be documented, then a pull request adding the
@@ -171,7 +171,7 @@ making and reviewing such changes. Before landing such commits, an effort
 must be made to determine the potential impact of the change in the ecosystem
 by analyzing current use and by validating such changes through ecosystem
 testing using the [Canary in the Goldmine](https://github.com/nodejs/citgm)
-tool. If a change cannot be made without ecosystem breakage, then CTC review is
+tool. If a change cannot be made without ecosystem breakage, then TSC review is
 required before landing the change as anything less than semver-major.
 
 If a determination is made that a particular internal API (for instance, an
@@ -183,7 +183,7 @@ breaking changes are made.
 ### Breaking Changes
 
 Backwards-incompatible changes may land on the master branch at any time after
-sufficient review by collaborators and approval of at least two CTC members.
+sufficient review by collaborators and approval of at least two TSC members.
 
 Examples of breaking changes include, but are not necessarily limited to,
 removal or redefinition of existing API arguments, changing return values
@@ -209,7 +209,7 @@ Exception to this rule is given in the following cases:
 Such changes *must* be handled as semver-major changes but MAY be landed
 without a [Deprecation cycle](#deprecation-cycle).
 
-From time-to-time, in particularly exceptional cases, the CTC may be asked to
+From time-to-time, in particularly exceptional cases, the TSC may be asked to
 consider and approve additional exceptions to this rule.
 
 Purely additive changes (e.g. adding new events to EventEmitter
@@ -244,7 +244,7 @@ Specifically:
   * Resolving critical security issues.
   * Fixing a critical bug (e.g. fixing a memory leak) requires a breaking
     change.
-  * There is CTC consensus that the change is required.
+  * There is TSC consensus that the change is required.
 * If a breaking commit does accidentally land in a Current or LTS branch, an
   attempt to fix the issue will be made before the next release; If no fix is
   provided then the commit will be reverted.
@@ -263,6 +263,32 @@ multiple commits. Commit metadata and the reason for the revert should be
 appended. Commit message rules about line length and subsystem can be ignored.
 A Pull Request should be raised and approved like any other change.
 
+### Introducing New Modules
+
+Semver-minor commits that introduce new core modules should be treated with
+extra care.
+
+The name of the new core module should not conflict with any existing
+module in the ecosystem unless a written agreement with the owner of those
+modules is reached to transfer ownership.
+
+If the new module name is free, a Collaborator should register a placeholder
+in the module registry as soon as possible, linking to the pull request that
+introduces the new core module.
+
+Pull requests introducing new core modules:
+
+* Must be left open for at least one week for review.
+* Must be labeled using the `ctc-review` label.
+* Must have signoff from at least two CTC members.
+
+New core modules must be landed with a [Stability Index][] of Experimental,
+and must remain Experimental until a semver-major release.
+
+For new modules that involve significant effort, non-trivial additions to
+Node.js or significant new capabilities, an [Enhancement Proposal][] is
+recommended but not required.
+
 ### Deprecations
 
 Deprecation refers to the identification of Public APIs that should no longer
@@ -294,7 +320,7 @@ operation of running code and therefore should not be viewed as breaking
 changes.
 
 Runtime Deprecations and End-of-life APIs (internal or public) *must* be
-handled as semver-major changes unless there is CTC consensus to land the
+handled as semver-major changes unless there is TSC consensus to land the
 deprecation as a semver-minor.
 
 All Documentation-Only and Runtime deprecations will be assigned a unique
@@ -320,18 +346,18 @@ request adding the deprecation lands in master). All deprecations included in
 a Node.js release should be listed prominently in the "Notable Changes" section
 of the release notes.
 
-### Involving the CTC
+### Involving the TSC
 
-Collaborators may opt to elevate pull requests or issues to the CTC for
-discussion by assigning the `ctc-review` label. This should be done
+Collaborators may opt to elevate pull requests or issues to the TSC for
+discussion by assigning the `tsc-review` label. This should be done
 where a pull request:
 
 - has a significant impact on the codebase,
 - is inherently controversial; or
 - has failed to reach consensus amongst the Collaborators who are
   actively participating in the discussion.
 
-The CTC should serve as the final arbiter where required.
+The TSC should serve as the final arbiter where required.
 
 ## Landing Pull Requests
 
@@ -512,9 +538,36 @@ your pull request shows the purple merged status then you should still
 add the "Landed in <commit hash>..<commit hash>" comment if you added
 multiple commits.
 
+### Troubleshooting
+
+Sometimes, when running `git push upstream master`, you may get an error message
+like this:
+
+```console
+To https://github.com/nodejs/node
+ ! [rejected]              master -> master (fetch first)
+error: failed to push some refs to 'https://github.com/nodejs/node'
+hint: Updates were rejected because the remote contains work that you do
+hint: not have locally. This is usually caused by another repository pushing
+hint: to the same ref. You may want to first integrate the remote changes
+hint: (e.g., 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+```
+
+That means a commit has landed since your last rebase against `upstream/master`.
+To fix this, fetch, rebase, run the tests again (to make sure no interactions
+between your changes and the new changes cause any problems), and push again:
+
+```sh
+git fetch upstream
+git rebase upstream/master
+make -j4 test
+git push upstream master
+```
+
 ### I Just Made a Mistake
 
-* Ping a CTC member.
+* Ping a TSC member.
 * `#node-dev` on freenode
 * With `git`, there's a way to override remote trees by force pushing
 (`git push -f`). This should generally be seen as forbidden (since
@@ -543,17 +596,17 @@ Once a Current branch enters LTS, changes in that branch are limited to bug
 fixes, security updates, possible npm updates, documentation updates, and
 certain performance improvements that can be demonstrated to not break existing
 applications. Semver-minor changes are only permitted if required for bug fixes
-and then only on a case-by-case basis with LTS WG and possibly Core Technical
-Committee (CTC) review. Semver-major changes are permitted only if required for
-security related fixes.
+and then only on a case-by-case basis with LTS WG and possibly Technical
+Steering Committee (TSC) review. Semver-major changes are permitted only if
+required for security related fixes.
 
 Once a Current branch moves into Maintenance mode, only **critical** bugs,
 **critical** security fixes, and documentation updates will be permitted.
 
 #### Landing semver-minor commits in LTS
 
 The default policy is to not land semver-minor or higher commits in any LTS
-branch. However, the LTS WG or CTC can evaluate any individual semver-minor
+branch. However, the LTS WG or TSC can evaluate any individual semver-minor
 commit and decide whether a special exception ought to be made. It is
 expected that such exceptions would be evaluated, in part, on the scope
 and impact of the changes on the code, the risk to ecosystem stability
@@ -563,7 +616,7 @@ commit will have for the ecosystem.
 Any collaborator who feels a semver-minor commit should be landed in an LTS
 branch should attach the `lts-agenda` label to the pull request. The LTS WG
 will discuss the issue and, if necessary, will escalate the issue up to the
-CTC for further discussion.
+TSC for further discussion.
 
 #### How are LTS Branches Managed?
 
@@ -615,3 +668,5 @@ release. This process of making a release will be a collaboration between the
 LTS working group and the Release team.
 
 [backporting guide]: doc/guides/backporting-to-release-lines.md
+[Stability Index]: https://github.com/nodejs/node/pull/doc/api/documentation.md#stability-index
+[Enhancement Proposal]: https://github.com/nodejs/node-eps