v8.7.0 proposal

.gitignore

@@ -69,11 +69,9 @@ ipch/
 /config_fips.gypi
 *-nodegyp*
 /gyp-mac-tool
-/dist-osx
 /npm.wxs
 /tools/msvs/npm.wixobj
 /tools/msvs/genfiles/
-/tools/osx-pkg.pmdoc/index.xml
 /test/addons/??_*/
 email.md
 deps/v8-*
@@ -101,6 +99,7 @@ deps/npm/node_modules/.bin/
 
 # build/release artifacts
 /*.tar.*
+/*.pkg
 /SHASUMS*.txt*
 
 # test artifacts

BUILDING.md

@@ -90,7 +90,7 @@ On macOS you will need to install the `Xcode Command Line Tools` by running
 installed, you can find them under the menu `Xcode -> Open Developer Tool ->
 More Developer Tools...`. This step will install `clang`, `clang++`, and
 `make`.
-* You may want to setup [firewall rules](tools/macosx-firewall.sh)
+* After building, 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.
@@ -128,6 +128,9 @@ To run the tests:
 $ make test
 ```
 
+At this point you are ready to make code changes and re-run the tests!
+Optionally, continue below.
+
 To run the tests and generate code coverage reports:
 
 ```console
@@ -144,7 +147,7 @@ and overwrites the `lib/` directory. To clean up after generating the coverage
 reports:
 
 ```console
-make coverage-clean
+$ make coverage-clean
 ```
 
 To build the documentation:

CHANGELOG.md

@@ -27,7 +27,8 @@ release.
 </tr>
 <tr>
  <td valign="top">
-<b><a href="doc/changelogs/CHANGELOG_V8.md#8.6.0">8.6.0</a></b><br/>
+<b><a href="doc/changelogs/CHANGELOG_V8.md#8.7.0">8.7.0</a></b><br/>
+<a href="doc/changelogs/CHANGELOG_V8.md#8.6.0">8.6.0</a><br/>
 <a href="doc/changelogs/CHANGELOG_V8.md#8.5.0">8.5.0</a><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/>

COLLABORATOR_GUIDE.md

@@ -8,7 +8,7 @@
  - [Internal vs. Public API](#internal-vs-public-api)
  - [Breaking Changes](#breaking-changes)
  - [Deprecations](#deprecations)
- - [Involving the TSC](#involving-the-TSC)
+ - [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)
@@ -123,44 +123,39 @@ level of V8 within Node.js is updated or new patches are floated on V8.
 
 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.
+represent the public API Node.js users should assume to be stable and which
+are part of the internal implementation details of Node.js itself. A rule of
+thumb is 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.
+
+The following general rules should be followed to determine which aspects of the
+Node.js API are internal:
+
+- All functionality exposed via `process.binding(...)` is internal.
+- All functionality implemented in `lib/internal/**/*.js` is internal unless it
+ is re-exported by code in `lib/*.js` or documented as part of the Node.js
+ Public API.
+- Any object property or method whose key is a non-exported `Symbol` is an
+ internal property.
+- Any object property or method whose key begins with the underscore `_` prefix
+ is internal unless it is documented as part of the Node.js Public API.
 - Any object, property, method, argument, behavior, or event not documented in
- the Node.js documentation is considered to be internal.
+ the Node.js documentation is 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.
+ are hidden behind the `NODE_WANT_INTERNALS` flag are 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
+for what qualifies as too much breakage is to be decided on a case-by-case
 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
-documentation is required in order for it to be considered part of the "public"
+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
@@ -232,17 +227,12 @@ 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.
+Because breaking (semver-major) changes are permitted to land on the master
+branch at any time, 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 the master branch. This potential instability is why Node.js offers
+distinct Current and LTS release streams that offer explicit stability
+guarantees.
 
 Specifically:
 
@@ -255,7 +245,7 @@ Specifically:
  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
+When any changes are landed on the master branch and it is determined that the
 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
@@ -297,18 +287,18 @@ recommended but not required.
 
 ### Deprecations
 
-Deprecation refers to the identification of Public APIs that should no longer
+_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.
+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:
+Node.js uses three 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.
+ but no functional changes are implemented in the code. There will be no
+ runtime deprecation warnings 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
@@ -320,12 +310,11 @@ Node.js uses three fundamental Deprecation levels:
 * *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.
+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
+Runtime Deprecations and End-of-life APIs (internal or public) must be
 handled as semver-major changes unless there is TSC consensus to land the
 deprecation as a semver-minor.
 
@@ -338,7 +327,7 @@ 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
+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.)
@@ -347,10 +336,10 @@ 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.
+mitigations with the ecosystem as soon as possible (preferably before the pull
+request adding the deprecation lands on the master branch). All deprecations
+included in a Node.js release should be listed prominently in the "Notable
+Changes" section of the release notes.
 
 ### Involving the TSC
 
@@ -367,16 +356,16 @@ The TSC should serve as the final arbiter where required.
 
 ## Landing Pull Requests
 
-* Please never use GitHub's green ["Merge Pull Request"](https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-using-the-github-web-interface) button.
+* Please never use GitHub's green ["Merge Pull Request"](https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-on-github) button.
  * If you do, please force-push removing the merge.
  * Reasons for not using the web interface button:
  * The merge method will add an unnecessary merge commit.
  * The rebase & merge method adds metadata to the commit title.
  * The rebase method changes the author.
  * The squash & merge method has been known to add metadata to the
  commit title.
- * If more than one author has contributed to the PR, only the
- latest author will be considered during the squashing.
+ * If more than one author has contributed to the PR, keep the most recent
+  author when squashing.
 
 Always modify the original commit message to include additional meta
 information regarding the change process:
@@ -394,8 +383,8 @@ information regarding the change process:
  - Useful for @mentions / contact list if something goes wrong in the PR.
  - Protects against the assumption that GitHub will be around forever.
 
-Review the commit message to ensure that it adheres to the guidelines
-outlined in the [contributing](./CONTRIBUTING.md#step-3-commit) guide.
+Review the commit message to ensure that it adheres to the guidelines outlined
+in the [contributing](./CONTRIBUTING.md#commit-message-guidelines) guide.
 
 See the commit log for examples such as
 [this one](https://github.com/nodejs/node/commit/b636ba8186) if unsure
@@ -520,7 +509,7 @@ commit message for that commit. This is a good moment to fix incorrect
 commit logs, ensure that they are properly formatted, and add
 `Reviewed-By` lines.
 * The commit message text must conform to the
-[commit message guidelines](./CONTRIBUTING.md#step-3-commit).
+[commit message guidelines](./CONTRIBUTING.md#commit-message-guidelines).
 
 Run tests (`make -j4 test` or `vcbuild test`). Even though there was a
 successful continuous integration run, other changes may have landed on master
@@ -594,7 +583,8 @@ commit final.
 Long Term Support (often referred to as *LTS*) guarantees application developers
 a 30 month support cycle with specific versions of Node.js.
 
-You can find more information [in the full LTS plan](https://github.com/nodejs/lts#lts-plan).
+You can find more information
+[in the full release plan](https://github.com/nodejs/Release#release-plan).
 
 #### How does LTS work?
 
@@ -627,10 +617,10 @@ TSC for further discussion.
 #### How are LTS Branches Managed?
 
 There are currently two LTS branches: `v6.x` and `v4.x`. Each of these is paired
-with a "staging" branch: `v6.x-staging` and `v4.x-staging`.
+with a staging branch: `v6.x-staging` and `v4.x-staging`.
 
-As commits land in `master`, they are cherry-picked back to each staging
-branch as appropriate. If the commit applies only to the LTS branch, the
+As commits land on the master branch, they are cherry-picked back to each
+staging branch as appropriate. If the commit applies only to the LTS branch, the
 PR must be opened against the *staging* branch. Commits are selectively
 pulled from the staging branch into the LTS branch only when a release is
 being prepared and may be pulled into the LTS branch in a different order
@@ -674,5 +664,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
+[Stability Index]: doc/api/documentation.md#stability-index
 [Enhancement Proposal]: https://github.com/nodejs/node-eps

CONTRIBUTING.md

@@ -32,6 +32,7 @@ expect throughout each step of the process.
  * [Commit message guidelines](#commit-message-guidelines)
  * [Step 5: Rebase](#step-5-rebase)
  * [Step 6: Test](#step-6-test)
+ * [Test Coverage](#test-coverage)
  * [Step 7: Push](#step-7-push)
  * [Step 8: Opening the Pull Request](#step-8-opening-the-pull-request)
  * [Step 9: Discuss and Update](#step-9-discuss-and-update)

LICENSE

@@ -551,8 +551,8 @@ The externally maintained libraries used by Node.js are:
  - stdint-msvc2008.h (from msinttypes), copyright Alexander Chemeris. Three
  clause BSD license.
 
- - pthread-fixes.h, pthread-fixes.c, copyright Google Inc. and Sony Mobile
- Communications AB. Three clause BSD license.
+ - pthread-fixes.c, copyright Google Inc. and Sony Mobile Communications AB.
+ Three clause BSD license.
 
  - android-ifaddrs.h, android-ifaddrs.c, copyright Berkeley Software Design
  Inc, Kenneth MacKay and Emergya (Cloud4all, FP7/2007-2013, grant agreement