From 2a8339ffadbe006545370a44090727ff66830980 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 6 Dec 2017 21:07:09 -0800 Subject: [PATCH 1/4] doc: improve readability of COLLABORATOR_GUIDE.md * convert run-on sentence to a bulleted list * standardize capitalization in "Collaborators" --- COLLABORATOR_GUIDE.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 95d5dccb59afef..4fed665fee7df1 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -130,7 +130,7 @@ can be fast-tracked and may be landed after a shorter delay: * Changes that fix regressions. When a pull request is deemed suitable to be fast-tracked, label it with -`fast-track`. The pull request can be landed once 2 or more collaborators +`fast-track`. The pull request can be landed once 2 or more Collaborators approve both the pull request and the fast-tracking request, and the necessary CI testing is done. @@ -221,15 +221,16 @@ on how to handle those types of changes. ### 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 TSC 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. +sufficient review by Collaborators and approval of at least two TSC members. + +Examples of breaking changes include: + +* removal or redefinition of existing API arguments +* changing return values +* removing or modifying existing properties on an options argument +* adding or removing errors +* altering expected timing of an event +* changing the side effects of using a particular API Purely additive changes (e.g. adding new events to `EventEmitter` implementations, adding new arguments to a method in a way that allows From 702d3b16a0337090d425c15d1c4ba51cc80778f5 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 6 Dec 2017 21:11:44 -0800 Subject: [PATCH 2/4] doc: improve readability of README.md Use consistent typography and other minor changes to Verifying Binaries section. --- README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index f4332771ac3e23..e37a2b70d82b02 100644 --- a/README.md +++ b/README.md @@ -116,11 +116,11 @@ documentation of the latest stable version. ### Verifying Binaries -Current, LTS, and Nightly download directories all contain a _SHASUMS256.txt_ +Current, LTS, and Nightly download directories all contain a SHASUMS256.txt file that lists the SHA checksums for each file available for download. -The _SHASUMS256.txt_ can be downloaded using curl. +The SHASUMS256.txt can be downloaded using `curl`. ```console $ curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt @@ -133,12 +133,9 @@ it through `sha256sum` with a command such as: $ grep node-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c - ``` -_(Where "node-vx.y.z.tar.gz" is the name of the file you have -downloaded)_ - -Additionally, Current and LTS releases (not Nightlies) have the GPG -detached signature of SHASUMS256.txt available as SHASUMS256.txt.sig. -You can use `gpg` to verify that SHASUMS256.txt has not been tampered with. +Current and LTS releases (but not Nightlies) also have the GPG detached +signature of SHASUMS256.txt available as SHASUMS256.txt.sig. You can use `gpg` +to verify that SHASUMS256.txt has not been tampered with. To verify SHASUMS256.txt has not been altered, you will first need to import all of the GPG keys of individuals authorized to create releases. They are @@ -149,8 +146,7 @@ Use a command such as this to import the keys: $ gpg --keyserver pool.sks-keyservers.net --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D ``` -_(See the bottom of this README for a full script to import active -release keys)_ +See the bottom of this README for a full script to import active release keys. Next, download the SHASUMS256.txt.sig for the release: From 03e4a1eeea4f39e583e9f5e56341ebbb70bf103f Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 6 Dec 2017 21:15:39 -0800 Subject: [PATCH 3/4] doc: improve text for Console constructor Make text for Console constructor more precise. --- doc/api/console.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/api/console.md b/doc/api/console.md index d9421043659cd4..6dac2a8a5e7c66 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -81,10 +81,9 @@ const { Console } = console; * `stdout` {Writable} * `stderr` {Writable} -Creates a new `Console` by passing one or two writable stream instances. -`stdout` is a writable stream to print log or info output. `stderr` -is used for warning or error output. If `stderr` is not passed, warning and error -output will be sent to `stdout`. +Creates a new `Console` with one or two writable stream instances. `stdout` is a +writable stream to print log or info output. `stderr` is used for warning or +error output. If `stderr` is not provided, `stdout` is used for `stderr`. ```js const output = fs.createWriteStream('./stdout.log'); From fd8d81326d2607062c7cc0992d8f252f7898de6d Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 6 Dec 2017 21:48:11 -0800 Subject: [PATCH 4/4] doc: immprove inode text in fs.md Rewrite and edit somewhat confusing paragraph about inodes and AIX in fs.md. --- doc/api/fs.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 8bc585d3a7291a..fb8d246f03d845 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -2568,12 +2568,9 @@ a new inode. The watch will emit an event for the delete but will continue watching the *original* inode. Events for the new inode will not be emitted. This is expected behavior. -On AIX, save and close of a file being watched causes two notifications - -one for adding new content, and one for truncation. Moreover, save and -close operations on some platforms cause inode changes that force watch -operations to become invalid and ineffective. AIX retains inode for the -lifetime of a file, that way though this is different from Linux / macOS, -this improves the usability of file watching. This is expected behavior. +AIX files retain the same inode for the lifetime of a file. Saving and closing a +watched file on AIX will result in two notifications (one for adding new +content, and one for truncation). #### Filename Argument