From d61ab57fe28f89236ee2b2c7561736933aa0f5fc Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 28 Nov 2017 21:37:55 -0500 Subject: [PATCH 1/2] doc: be concise about serial commas There is nothing controversial about serial commas and there is no need to hedge bets on it. Simply instruct people to use serial commas. --- doc/STYLE_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 9cdbf0d7b63631..d1bf5208595c20 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -14,7 +14,7 @@ human reviewers. * American English spelling is preferred. "Capitalize" vs. "Capitalise", "color" vs. "colour", etc. -* Though controversial, the [Oxford comma][] is preferred for clarity's sake. +* Use [serial commas][]. * Generally avoid personal pronouns in reference documentation ("I", "you", "we"). * Pronouns are acceptable in more colloquial documentation, like guides. @@ -75,6 +75,6 @@ [Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash [Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types -[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma +[serial commas]: https://en.wikipedia.org/wiki/Serial_comma [The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage [plugin]: http://editorconfig.org/#download From a95ce6b098468ae5716dfc5842f90e8445425c90 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 28 Nov 2017 21:53:24 -0500 Subject: [PATCH 2/2] doc: add missing serial commas --- COLLABORATOR_GUIDE.md | 2 +- CONTRIBUTING.md | 4 ++-- CPP_STYLE_GUIDE.md | 4 ++-- README.md | 2 +- doc/api/addons.md | 2 +- doc/api/buffer.md | 2 +- doc/api/child_process.md | 2 +- doc/api/crypto.md | 6 +++--- doc/api/fs.md | 10 +++++----- doc/api/http2.md | 8 ++++---- doc/api/n-api.md | 6 +++--- doc/api/os.md | 2 +- doc/api/process.md | 4 ++-- doc/api/tls.md | 2 +- doc/releases.md | 2 +- 15 files changed, 29 insertions(+), 29 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index c65317dd570dcf..95d5dccb59afef 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -33,7 +33,7 @@ - [How is an LTS release cut?](#how-is-an-lts-release-cut) This document contains information for Collaborators of the Node.js -project regarding maintaining the code, documentation and issues. +project regarding maintaining the code, documentation, and issues. Collaborators should be familiar with the guidelines for new contributors in [CONTRIBUTING.md](./CONTRIBUTING.md) and also diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9cd14793ef58a2..9f8f89cdaa999e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,7 +74,7 @@ for any individual to *act* in such a manner that is not in violation of the strict letter of the Code of Conduct guidelines while still going completely against the spirit of what that Code is intended to accomplish. -Open, diverse and inclusive communities live and die on the basis of trust. +Open, diverse, and inclusive communities live and die on the basis of trust. Contributors can disagree with one another so long as they trust that those disagreements are in good faith and everyone is working towards a common goal. @@ -177,7 +177,7 @@ Node.js changed that broke the module. Once an issue has been opened, it is not uncommon for there to be discussion around it. Some contributors may have differing opinions about the issue, including whether the behavior being seen is a bug or a feature. This discussion -is part of the process and should be kept focused, helpful and professional. +is part of the process and should be kept focused, helpful, and professional. Short, clipped responses—that provide neither additional context nor supporting detail—are not helpful or professional. To many, such responses are simply diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index 1dad8592f9694c..d3afd3c1abb7da 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -7,7 +7,7 @@ * [4 spaces of indentation for statement continuations](#4-spaces-of-indentation-for-statement-continuations) * [Align function arguments vertically](#align-function-arguments-vertically) * [Initialization lists](#initialization-lists) -* [CamelCase for methods, functions and classes](#camelcase-for-methods-functions-and-classes) +* [CamelCase for methods, functions, and classes](#camelcase-for-methods-functions-and-classes) * [snake\_case for local variables and parameters](#snake_case-for-local-variables-and-parameters) * [snake\_case\_ for private class fields](#snake_case_-for-private-class-fields) * [Space after `template`](#space-after-template) @@ -87,7 +87,7 @@ HandleWrap::HandleWrap(Environment* env, handle_(handle) { ``` -## CamelCase for methods, functions and classes +## CamelCase for methods, functions, and classes Exceptions are simple getters/setters, which are named `property_name()` and `set_property_name()`, respectively. diff --git a/README.md b/README.md index 388ad68097b4eb..e6568c466f245b 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,7 @@ 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. diff --git a/doc/api/addons.md b/doc/api/addons.md index 3dd98e3e73c6f8..9ccf07f777a5ba 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -20,7 +20,7 @@ involving knowledge of several components and APIs : threads and all of the asynchronous behaviors of the platform. It also serves as a cross-platform abstraction library, giving easy, POSIX-like access across all major operating systems to many common system tasks, such - as interacting with the filesystem, sockets, timers and system events. libuv + as interacting with the filesystem, sockets, timers, and system events. libuv also provides a pthreads-like threading abstraction that may be used to power more sophisticated asynchronous Addons that need to move beyond the standard event loop. Addon authors are encouraged to think about how to diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 3246e069302a23..58d425489edd61 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -154,7 +154,7 @@ changes: --> `Buffer` instances are commonly used to represent sequences of encoded characters -such as UTF-8, UCS2, Base64 or even Hex-encoded data. It is possible to +such as UTF-8, UCS2, Base64, or even Hex-encoded data. It is possible to convert back and forth between `Buffer` instances and ordinary JavaScript strings by using an explicit character encoding. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 8be21a1d07d908..801c4251942e66 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -628,7 +628,7 @@ pipes between the parent and child. The value is one of the following: 5. Positive integer - The integer value is interpreted as a file descriptor that is is currently open in the parent process. It is shared with the child process, similar to how {Stream} objects can be shared. -6. `null`, `undefined` - Use default value. For stdio fds 0, 1 and 2 (in other +6. `null`, `undefined` - Use default value. For stdio fds 0, 1, and 2 (in other words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the default is `'ignore'`. diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 9d6e344667520e..c490ee71ddb7e0 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -5,7 +5,7 @@ > Stability: 2 - Stable The `crypto` module provides cryptographic functionality that includes a set of -wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign and verify functions. +wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions. Use `require('crypto')` to access this module. @@ -1254,7 +1254,7 @@ In line with OpenSSL's recommendation to use pbkdf2 instead of [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on their own using [`crypto.pbkdf2()`][] and to use [`crypto.createCipheriv()`][] to create the `Cipher` object. Users should not use ciphers with counter mode -(e.g. CTR, GCM or CCM) in `crypto.createCipher()`. A warning is emitted when +(e.g. CTR, GCM, or CCM) in `crypto.createCipher()`. A warning is emitted when they are used in order to avoid the risk of IV reuse that causes vulnerabilities. For the case when IV is reused in GCM, see [Nonce-Disrespecting Adversaries][] for details. @@ -2034,7 +2034,7 @@ Based on the recommendations of [NIST SP 800-131A][]: - MD5 and SHA-1 are no longer acceptable where collision resistance is required such as digital signatures. -- The key used with RSA, DSA and DH algorithms is recommended to have +- The key used with RSA, DSA, and DH algorithms is recommended to have at least 2048 bits and that of the curve of ECDSA and ECDH at least 224 bits, to be safe to use for several years. - The DH groups of `modp1`, `modp2` and `modp5` have a key size diff --git a/doc/api/fs.md b/doc/api/fs.md index 600f6db59bef4e..0bbfd41d80818c 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1881,7 +1881,7 @@ Linux, and Windows, an error will be returned. On FreeBSD, a representation of the directory's contents will be returned. ```js -// macOS, Linux and Windows +// macOS, Linux, and Windows fs.readFile('', (err, data) => { // => [Error: EISDIR: illegal operation on a directory, read ] }); @@ -1929,7 +1929,7 @@ string. Otherwise it returns a buffer. behavior of `fs.readFileSync()` is platform-specific. ```js -// macOS, Linux and Windows +// macOS, Linux, and Windows fs.readFileSync(''); // => [Error: EISDIR: illegal operation on a directory, read ] @@ -3043,7 +3043,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's S_IRWXU - File mode indicating readable, writable and executable by owner. + File mode indicating readable, writable, and executable by owner. S_IRUSR @@ -3059,7 +3059,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's S_IRWXG - File mode indicating readable, writable and executable by group. + File mode indicating readable, writable, and executable by group. S_IRGRP @@ -3075,7 +3075,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's S_IRWXO - File mode indicating readable, writable and executable by others. + File mode indicating readable, writable, and executable by others. S_IROTH diff --git a/doc/api/http2.md b/doc/api/http2.md index 86b9c5701f84d6..120ecb71e2cb02 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1264,7 +1264,7 @@ added: v8.4.0 In `Http2Server`, there is no `'clientError'` event as there is in HTTP1. However, there are `'socketError'`, `'sessionError'`, and -`'streamError'`, for error happened on the socket, session or stream +`'streamError'`, for error happened on the socket, session, or stream respectively. #### Event: 'socketError' @@ -1857,7 +1857,7 @@ performance. There are several types of error conditions that may arise when using the `http2` module: -Validation Errors occur when an incorrect argument, option or setting value is +Validation Errors occur when an incorrect argument, option, or setting value is passed in. These will always be reported by a synchronous `throw`. State Errors occur when an action is attempted at an incorrect time (for @@ -2229,7 +2229,7 @@ added: v8.4.0 * {net.Socket|tls.TLSSocket} Returns a Proxy object that acts as a `net.Socket` (or `tls.TLSSocket`) but -applies getters, setters and methods based on HTTP/2 logic. +applies getters, setters, and methods based on HTTP/2 logic. `destroyed`, `readable`, and `writable` properties will be retrieved from and set on `request.stream`. @@ -2601,7 +2601,7 @@ added: v8.4.0 * {net.Socket|tls.TLSSocket} Returns a Proxy object that acts as a `net.Socket` (or `tls.TLSSocket`) but -applies getters, setters and methods based on HTTP/2 logic. +applies getters, setters, and methods based on HTTP/2 logic. `destroyed`, `readable`, and `writable` properties will be retrieved from and set on `response.stream`. diff --git a/doc/api/n-api.md b/doc/api/n-api.md index f1587f4848b807..c91927a4ee8304 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -2257,7 +2257,7 @@ following forms: - Named: a simple UTF8-encoded string - Integer-Indexed: an index value represented by `uint32_t` - JavaScript value: these are represented in N-API by `napi_value`. This can -be a `napi_value` representing a String, Number or Symbol. +be a `napi_value` representing a String, Number, or Symbol. N-API values are represented by the type `napi_value`. Any N-API call that requires a JavaScript value takes in a `napi_value`. @@ -3471,8 +3471,8 @@ napi_status napi_get_node_version(napi_env env, Returns `napi_ok` if the API succeeded. -This function fills the `version` struct with the major, minor and patch version -of Node that is currently running, and the `release` field with the +This function fills the `version` struct with the major, minor, and patch +version of Node.js that is currently running, and the `release` field with the value of [`process.release.name`][`process.release`]. The returned buffer is statically allocated and does not need to be freed. diff --git a/doc/api/os.md b/doc/api/os.md index dca9b266f7806d..e77238021c6085 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -453,7 +453,7 @@ The following signal constants are exported by `os.constants.signals`: SIGILL Sent to a process to notify that it has attempted to perform an illegal, - malformed, unknown or privileged instruction. + malformed, unknown, or privileged instruction. SIGTRAP diff --git a/doc/api/process.md b/doc/api/process.md index 755dfb537c93ed..054f8678f3f35c 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -275,7 +275,7 @@ A process warning is similar to an error in that it describes exceptional conditions that are being brought to the user's attention. However, warnings are not part of the normal Node.js and JavaScript error handling flow. Node.js can emit warnings whenever it detects bad coding practices that could -lead to sub-optimal application performance, bugs or security vulnerabilities. +lead to sub-optimal application performance, bugs, or security vulnerabilities. The listener function is called with a single `warning` argument whose value is an `Error` object. There are three key properties that describe the warning: @@ -1297,7 +1297,7 @@ objects managed by V8. `rss`, Resident Set Size, is the amount of space occupied in the main memory device (that is a subset of the total allocated memory) for the process, which includes the _heap_, _code segment_ and _stack_. -The _heap_ is where objects, strings and closures are stored. Variables are +The _heap_ is where objects, strings, and closures are stored. Variables are stored in the _stack_ and the actual JavaScript code resides in the _code segment_. diff --git a/doc/api/tls.md b/doc/api/tls.md index bba044a36d46e3..a9b5a5d0dcd1f4 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -104,7 +104,7 @@ not required and a default ECDHE curve will be used. The `ecdhCurve` property can be used when creating a TLS Server to specify the list of names of supported curves to use, see [`tls.createServer()`] for more info. -### ALPN, NPN and SNI +### ALPN, NPN, and SNI diff --git a/doc/releases.md b/doc/releases.md index c3d21407acf298..be3d3bcdb7af30 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -214,7 +214,7 @@ If you have an error on Windows and need to start again, be aware that you'll ge ARMv7 takes the longest to compile. Unfortunately ccache isn't as effective on release builds, I think it's because of the additional macro settings that go in to a release build that nullify previous builds. Also most of the release build machines are separate to the test build machines so they don't get any benefit from ongoing compiles between releases. You can expect 1.5 hours for the ARMv7 builder to complete and you should normally wait for this to finish. It is possible to rush a release out if you want and add additional builds later but we normally provide ARMv7 from initial promotion. -You do not have to wait for the ARMv6 / Raspberry PI builds if they take longer than the others. It is only necessary to have the main Linux (x64 and x86), macOS .pkg and .tar.gz, Windows (x64 and x86) .msi and .exe, source, headers and docs (both produced currently by an macOS worker). **If you promote builds _before_ ARM builds have finished, you must repeat the promotion step for the ARM builds when they are ready**. +You do not have to wait for the ARMv6 / Raspberry PI builds if they take longer than the others. It is only necessary to have the main Linux (x64 and x86), macOS .pkg and .tar.gz, Windows (x64 and x86) .msi and .exe, source, headers, and docs (both produced currently by an macOS worker). **If you promote builds _before_ ARM builds have finished, you must repeat the promotion step for the ARM builds when they are ready**. ### 9. Test the Build