Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: more assorted fixes #17519

Closed
wants to merge 4 commits into from
Closed

doc: more assorted fixes #17519

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2a8339f
doc: improve readability of COLLABORATOR_GUIDE.md
Trott Dec 7, 2017
702d3b1
doc: improve readability of README.md
Trott Dec 7, 2017
03e4a1e
doc: improve text for Console constructor
Trott Dec 7, 2017
fd8d813
doc: immprove inode text in fs.md
Trott Dec 7, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't it be collaborators instead of Collaborators ? Its not the first word in a new line but part of the line right ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Collaborator is a title and it should be capitalized.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we be linting for capitalizing Collaborator(s) then?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't it be collaborators instead of Collaborators ?

A case could be made for lower case or capitalizing. While I would prefer lower case myself, I am far more concerned with consistency. Since we capitalize it multiple times elsewhere in this and other documents, capitalizing it here normalizes things without a lot of needless churn.

approve both the pull request and the fast-tracking request, and the necessary
CI testing is done.

Expand Down Expand Up @@ -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
Expand Down
16 changes: 6 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

excluding Nightlies sounds more correct than but not Nightlies

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"but not Nightlies" sounds better to me because the two preceding items do not include (or in any way reference) Nightlies so "excluding" doesn't make sense.

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

Expand Down
7 changes: 3 additions & 4 deletions doc/api/console.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
9 changes: 3 additions & 6 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down