Proposal - 7.6.0 (Current)

.eslintrc.yaml

@@ -3,7 +3,7 @@ env:
   es6: true
 
 parserOptions:
-  ecmaVersion: 2016
+  ecmaVersion: 2017
 
 rules:
   # Possible Errors
@@ -40,6 +40,7 @@ rules:
   no-octal: 2
   no-redeclare: 2
   no-self-assign: 2
+  no-throw-literal: 2
   no-unused-labels: 2
   no-useless-call: 2
   no-useless-escape: 2

CHANGELOG.md

@@ -28,7 +28,8 @@ release.
 </tr>
 <tr>
   <td valign="top">
-    <b><a href="doc/changelogs/CHANGELOG_V7.md#7.5.0">7.5.0</a></b><br/>
+    <b><a href="doc/changelogs/CHANGELOG_V7.md#7.6.0">7.6.0</a></b><br/>
+    <a href="doc/changelogs/CHANGELOG_V7.md#7.5.0">7.5.0</a><br/>
     <a href="doc/changelogs/CHANGELOG_V7.md#7.4.0">7.4.0</a><br/>
     <a href="doc/changelogs/CHANGELOG_V7.md#7.3.0">7.3.0</a><br/>
     <a href="doc/changelogs/CHANGELOG_V7.md#7.2.1">7.2.1</a><br/>

COLLABORATOR_GUIDE.md

@@ -4,6 +4,9 @@
 
 * [Issues and Pull Requests](#issues-and-pull-requests)
 * [Accepting Modifications](#accepting-modifications)
+ - [Internal vs. Public API](#internal-vs-public-api)
+ - [Breaking Changes](#breaking-changes)
+ - [Deprecations](#deprecations)
  - [Involving the CTC](#involving-the-ctc)
 * [Landing Pull Requests](#landing-pull-requests)
  - [Technical HOWTO](#technical-howto)
@@ -84,6 +87,206 @@ All pull requests that modify executable code should be subjected to
 continuous integration tests on the
 [project CI server](https://ci.nodejs.org/).
 
+### Internal vs. Public API
+
+Due to the nature of the JavaScript language, it can often be difficult to
+establish a clear distinction between which parts of the Node.js implementation
+represent the "public" API Node.js users should assume to be stable and which
+are considered part of the "internal" implementation detail of Node.js itself.
+A general rule of thumb has been to base the determination off what
+functionality is actually *documented* in the official Node.js API
+documentation. However, it has been repeatedly demonstrated that either the
+documentation does not completely cover implemented behavior or that Node.js
+users have come to rely heavily on undocumented aspects of the Node.js
+implementation.
+
+While there are numerous exceptions, the following general rules should be
+followed to determine which aspects of the Node.js API are considered
+"internal":
+
+- Any and all functionality exposed via `process.binding(...)` is considered to
+  be internal and *not* part of the Node.js Public API.
+- Any and all functionality implemented in `lib/internal/**/*.js` that is not
+  re-exported by code in `lib/*.js`, or is not documented as part of the
+  Node.js Public API, is considered to be internal.
+- Any object property or method whose key is a non-exported `Symbol` is
+  considered to be an internal property.
+- Any object property or method whose key begins with the underscore `_` prefix,
+  and is not documented as part of the Node.js Public API, is considered to be
+  an internal property.
+- Any object, property, method, argument, behavior, or event not documented in
+  the Node.js documentation is considered to be internal.
+- Any native C/C++ APIs/ABIs exported by the Node.js `*.h` header files that
+  are hidden behind the `NODE_WANT_INTERNALS` flag are considered to be
+  internal.
+
+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.
+
+If it is determined that a currently undocumented object, property, method,
+argument, or event *should* be documented, then a pull request adding the
+documentation is required in order for it to be considered part of the "public"
+API.
+
+Making a determination about whether something *should* be documented can be
+difficult and will need to be handled on a case-by-case basis. For instance, if
+one documented API cannot be used successfully without the use of a second
+*currently undocumented* API, then the second API *should* be documented. If
+using an API in a manner currently undocumented achieves a particular useful
+result, a decision will need to be made whether or not that falls within the
+supported scope of that API; and if it does, it should be documented.
+
+Breaking changes to internal elements are permitted in semver-patch or
+semver-minor commits but Collaborators should take significant care when
+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
+required before landing the change as anything less than semver-major.
+
+If a determination is made that a particular internal API (for instance, an
+underscore `_` prefixed property) is sufficiently relied upon by the ecosystem
+such that any changes may break user code, then serious consideration should be
+given to providing an alternative Public API for that functionality before any
+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.
+
+Examples of breaking changes include, but are not necessarily limited to,
+removal or redefinition of existing API arguments, changing return values
+(except when return values do not currently exist), removing or modifying
+existing properties on an options argument, adding or removing errors,
+changing error messages in any way, altering expected timing of an event (e.g.
+moving from sync to async responses or vice versa), and changing the
+non-internal side effects of using a particular API.
+
+With a few notable exceptions outlined below, when backwards incompatible
+changes to a *Public* API are necessary, the existing API *must* be deprecated
+*first* and the new API either introduced in parallel or added after the next
+major Node.js version following the deprecation as a replacement for the
+deprecated API. In other words, as a general rule, existing *Public* APIs
+*must not* change (in a backwards incompatible way) without a deprecation.
+
+Exception to this rule is given in the following cases:
+
+* Adding or removing errors thrown or reported by a Public API;
+* Changing error messages;
+* Altering the timing and non-internal side effects of the Public API.
+
+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
+consider and approve additional exceptions to this rule.
+
+Purely additive changes (e.g. adding new events to EventEmitter
+implementations, adding new arguments to a method in a way that allows
+existing code to continue working without modification, or adding new
+properties to an options argument) are handled as semver-minor changes.
+
+Note that errors thrown, along with behaviors and APIs implemented by
+dependencies of Node.js (e.g. those originating from V8) are generally not
+under the control of Node.js and therefore *are not directly subject to this
+policy*. However, care should still be taken when landing updates to
+dependencies when it is known or expected that breaking changes to error
+handling may have been made. Additional CI testing may be required.
+
+#### When breaking changes actually break things
+
+Breaking changes are difficult primarily because they change the fundamental
+assumptions a user of Node.js has when writing their code and can cause
+existing code to stop functioning as expected -- costing developers and users
+time and energy to fix.
+
+Because breaking (semver-major) changes are permitted to land in master at any
+time, it should be *understood and expected* that at least some subset of the
+user ecosystem *may* be adversely affected *in the short term* when attempting
+to build and use Node.js directly from master. This potential instability is
+precisely why Node.js offers distinct Current and LTS release streams that
+offer explicit stability guarantees.
+
+Specifically:
+
+* Breaking changes should *never* land in Current or LTS except when:
+  * 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.
+* 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.
+
+When any change is landed in master, and it is determined that the such
+changes *do* break existing code, a decision may be made to revert those
+changes either temporarily or permanently. However, the decision to revert or
+not can often be based on many complex factors that are not easily codified. It
+is also possible that the breaking commit can be labeled retroactively as a
+semver-major change that will not be backported to Current or LTS branches.
+
+### Deprecations
+
+Deprecation refers to the identification of Public APIs that should no longer
+be used and that may be removed or modified in non-backwards compatible ways in
+a future major release of Node.js. Deprecation *may* be used with internal APIs
+if there is expected impact on the user community.
+
+Node.js uses three fundamental Deprecation levels:
+
+* *Documentation-Only Deprecation* refers to elements of the Public API that are
+  being staged for deprecation in a future Node.js major release. An explicit
+  notice indicating the deprecated status is added to the API documentation
+  *but no functional changes are implemented in the code*. There will be no
+  runtime deprecation warning emitted for such deprecations.
+
+* *Runtime Deprecation* refers to the use of process warnings emitted at
+  runtime the first time that a deprecated API is used. A command-line
+  switch can be used to escalate such warnings into runtime errors that will
+  cause the Node.js process to exit. As with Documentation-Only Deprecation,
+  the documentation for the API must be updated to clearly indicate the
+  deprecated status.
+
+* *End-of-life* refers to APIs that have gone through Runtime Deprecation and
+  are ready to be removed from Node.js entirely.
+
+Documentation-Only Deprecations *may* be handled as semver-minor or
+semver-major changes. Such deprecations have no impact on the successful
+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
+deprecation as a semver-minor.
+
+All Documentation-Only and Runtime deprecations will be assigned a unique
+identifier that can be used to persistently refer to the deprecation in
+documentation, emitted process warnings, or errors thrown. Documentation for
+these identifiers will be included in the Node.js API documentation and will
+be immutable once assigned. Even if End-of-Life code is removed from Node.js,
+the documentation for the assigned deprecation identifier must remain in the
+Node.js API documentation.
+
+<a id="deprecation-cycle"></a>
+A "Deprecation cycle" is one full Node.js major release during which an API
+has been in one of the three Deprecation levels. (Note that Documentation-Only
+Deprecations may land in a Node.js minor release but must not be upgraded to
+a Runtime Deprecation until the next major release.)
+
+No API can be moved to End-of-life without first having gone through a
+Runtime Deprecation cycle.
+
+A best effort will be made to communicate pending deprecations and associated
+mitigations with the ecosystem as soon as possible (preferably *before* the pull
+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
 
 Collaborators may opt to elevate pull requests or issues to the CTC for
@@ -291,15 +494,15 @@ You can find more information [in the full LTS plan](https://github.com/nodejs/l
 
 #### How does LTS work?
 
-Once a stable branch enters LTS, changes in that branch are limited to bug
+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.
 
-Once a stable branch moves into Maintenance mode, only **critical** bugs,
+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

CONTRIBUTING.md

@@ -16,7 +16,7 @@ For general help using Node.js, please file an issue at the
 [Node.js help repository](https://github.com/nodejs/help/issues).
 
 Discussion of non-technical topics including subjects like intellectual
-property, trademark and high level project questions should move to the
+property, trademark, and high level project questions should move to the
 [Technical Steering Committee (TSC)](https://github.com/nodejs/TSC/issues)
 instead.
 
@@ -109,8 +109,8 @@ changed and why. Follow these guidelines when writing one:
    lowercase with the exception of proper nouns, acronyms, and the ones that
    refer to code, like function/variable names. The description should
    be prefixed with the name of the changed subsystem and start with an
-   imperative verb, for example, "net: add localAddress and localPort
-   to Socket".
+   imperative verb. Example: "net: add localAddress and localPort
+   to Socket"
 2. Keep the second line blank.
 3. Wrap all other lines at 72 columns.
 
@@ -121,11 +121,11 @@ subsystem: explain the commit in one line
 
 Body of commit message is a few lines of text, explaining things
 in more detail, possibly giving some background about the issue
-being fixed, etc. etc.
+being fixed, etc.
 
 The body of the commit message can be several paragraphs, and
 please do proper word-wrap and keep columns shorter than about
-72 characters or so. That way `git log` will show things
+72 characters or so. That way, `git log` will show things
 nicely even when it is indented.
 ```
 
@@ -170,19 +170,21 @@ $ ./configure && make -j4 test
 Windows:
 
 ```text
- .\vcbuild nosign test
+> vcbuild test
 ```
 
 (See the [BUILDING.md](./BUILDING.md) for more details.)
 
-Make sure the linter is happy and that all tests pass. Please, do not submit
-patches that fail either check.
+Make sure the linter does not report any issues and that all tests pass. Please
+do not submit patches that fail either check.
 
-Running `make test`/`.\vcbuild nosign test` will run the linter as well unless one or
+Running `make test`/`vcbuild test` will run the linter as well unless one or
 more tests fail.
 
 If you want to run the linter without running tests, use
-`make lint`/`.\vcbuild nosign jslint`.
+`make lint`/`vcbuild jslint`. At this time, only JavaScript linting is
+available on Windows. `make lint` on POSIX will run both JavaScript linting and
+C++ linting.
 
 If you are updating tests and just want to run a single test to check it, you
 can use this syntax to run it exactly as the test harness would:
@@ -214,7 +216,7 @@ Pull requests are usually reviewed within a few days.
 ### Step 7: Discuss and update
 
 You will probably get feedback or requests for changes to your Pull Request.
-This is a big part of the submission process, so don't be disheartened!
+This is a big part of the submission process so don't be disheartened!
 
 To make changes to an existing Pull Request, make the changes to your branch.
 When you push that branch to your fork, GitHub will automatically update the
@@ -252,15 +254,15 @@ If in doubt, you can always ask for guidance in the Pull Request or on
 
 Feel free to post a comment in the Pull Request to ping reviewers if you are
 awaiting an answer on something. If you encounter words or acronyms that
-seem unfamiliar, check out this
+seem unfamiliar, refer to this
 [glossary](https://sites.google.com/a/chromium.org/dev/glossary).
 
 Note that multiple commits often get squashed when they are landed (see the
 notes about [commit squashing](#commit-squashing)).
 
 ### Step 8: Landing
 
-In order to get landed, a Pull Request needs to be reviewed and
+In order to land, a Pull Request needs to be reviewed and
 [approved](#getting-approvals-for-your-pull-request) by
 at least one Node.js Collaborator and pass a
 [CI (Continuous Integration) test run](#ci-testing).
@@ -280,8 +282,8 @@ your name on it. Congratulations and thanks for your contribution!
 
 ### Commit Squashing
 
-When the commits in your Pull Request get landed, they will be squashed
-into one commit per logical change, with metadata added to the commit
+When the commits in your Pull Request land, they will be squashed
+into one commit per logical change. Metadata will be added to the commit
 message (including links to the Pull Request, links to relevant issues,
 and the names of the reviewers). The commit history of your Pull Request,
 however, will stay intact on the Pull Request page.
@@ -311,9 +313,9 @@ Every Pull Request needs to be tested
 to make sure that it works on the platforms that Node.js
 supports. This is done by running the code through the CI system.
 
-Only a Collaborator can request a CI run. Usually one of them will do it
+Only a Collaborator can start a CI run. Usually one of them will do it
 for you as approvals for the Pull Request come in.
-If not, you can ask a Collaborator to request a CI run.
+If not, you can ask a Collaborator to start a CI run.
 
 ### Waiting Until the Pull Request Gets Landed
 

LICENSE

@@ -1071,23 +1071,6 @@ The externally maintained libraries used by Node.js are:
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   """
 
-- node-weak, located at test/gc/node_modules/weak, is licensed as follows:
-  """
-    Copyright (c) 2011, Ben Noordhuis <info@bnoordhuis.nl>
-
-    Permission to use, copy, modify, and/or distribute this software for any
-    purpose with or without fee is hereby granted, provided that the above
-    copyright notice and this permission notice appear in all copies.
-
-    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-  """
-
 - v8_inspector, located at deps/v8_inspector/third_party/v8_inspector, is licensed as follows:
   """
     // Copyright 2015 The Chromium Authors. All rights reserved.