FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: enhance guides by fixing and making grammar more consistent · nodejs/node@182aaf5 · GitHub

/ node Public

Commit 182aaf5

Browse files
ChrisAHolland
authored and
codebytere
committed
doc: enhance guides by fixing and making grammar more consistent
PR-URL: #33152 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
1 parent d3e2fc8 commit 182aaf5

4 files changed

Lines changed: 59 additions & 55 deletions

File tree

‎doc/guides/collaborator-guide.md‎

Lines changed: 30 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -109,8 +109,8 @@ review by @-mention.
109109
See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker).
110110

111111
If you are the first Collaborator to approve a pull request that has no CI yet,
112-
please [start one](#testing-and-ci). Please also start a new CI if the PR
113-
creator pushed new code since the last CI run.
112+
please [start one](#testing-and-ci). Please also start a new CI if the
113+
pull request creator pushed new code since the last CI run.
114114

115115
### Consensus Seeking
116116

@@ -269,22 +269,22 @@ master branch.
269269

270270
Examples of breaking changes include:
271271

272-
* removal or redefinition of existing API arguments
273-
* changing return values
274-
* removing or modifying existing properties on an options argument
275-
* adding or removing errors
276-
* altering expected timing of an event
277-
* changing the side effects of using a particular API
272+
* Removal or redefinition of existing API arguments.
273+
* Changing return values.
274+
* Removing or modifying existing properties on an options argument.
275+
* Adding or removing errors.
276+
* Altering expected timing of an event.
277+
* Changing the side effects of using a particular API.
278278

279279
#### Breaking Changes and Deprecations
280280

281281
Existing stable public APIs that change in a backward-incompatible way must
282282
undergo deprecation. The exceptions to this rule are:
283283

284-
* Adding or removing errors thrown or reported by a public API;
285-
* Changing error messages for errors without error code;
286-
* Altering the timing and non-internal side effects of the public API;
287-
* Changes to errors thrown by dependencies of Node.js, such as V8;
284+
* Adding or removing errors thrown or reported by a public API.
285+
* Changing error messages for errors without error code.
286+
* Altering the timing and non-internal side effects of the public API.
287+
* Changes to errors thrown by dependencies of Node.js, such as V8.
288288
* One-time exceptions granted by the TSC.
289289

290290
For more information, see [Deprecations](#deprecations).
@@ -310,7 +310,7 @@ after-the-fact.
310310
Revert commits with `git revert <HASH>` or `git revert <FROM>..<TO>`. The
311311
generated commit message will not have a subsystem and may violate line length
312312
rules. That is OK. Append the reason for the revert and any `Refs` or `Fixes`
313-
metadata. Raise a Pull Request like any other change.
313+
metadata. Raise a pull request like any other change.
314314

315315
### Introducing New Modules
316316

@@ -400,10 +400,10 @@ deprecation level of an API.
400400
Collaborators may opt to elevate pull requests or issues to the [TSC][].
401401
Do this if a pull request or issue:
402402

403-
* is labeled `semver-major`, or
404-
* has a significant impact on the codebase, or
405-
* is controversial, or
406-
* is at an impasse among Collaborators who are participating in the discussion.
403+
* Is labeled `semver-major`, or
404+
* Has a significant impact on the codebase, or
405+
* Is controversial, or
406+
* Is at an impasse among Collaborators who are participating in the discussion.
407407

408408
@-mention the `@nodejs/tsc` GitHub team if you want to elevate an issue to the
409409
[TSC][]. Do not use the GitHub UI on the right-hand side to assign to
@@ -573,7 +573,7 @@ for that commit. This is an opportunity to fix commit messages.
573573
* The commit message text must conform to the [commit message guidelines][].
574574
* <a name="metadata"></a>Change the original commit message to include metadata. (The
575575
[`git node metadata`][git-node-metadata] command can generate the metadata
576-
for you.)
576+
for you).
577577

578578
* Required: A `PR-URL:` line that references the full GitHub URL of the pull
579579
request. This makes it easy to trace a commit back to the conversation that
@@ -584,7 +584,8 @@ for that commit. This is an opportunity to fix commit messages.
584584
background.
585585
* Required: A `Reviewed-By: Name <email>` line for each Collaborator who
586586
reviewed the change.
587-
* Useful for @mentions / contact list if something goes wrong in the PR.
587+
* Useful for @mentions / contact list if something goes wrong in the
588+
pull request.
588589
* Protects against the assumption that GitHub will be around forever.
589590

590591
Other changes may have landed on master since the successful CI run. As a
@@ -599,12 +600,13 @@ $ git rev-list upstream/master...HEAD | xargs core-validate-commit
599600

600601
Optional: For your own commits, force push the amended commit to the pull
601602
request branch. If your branch name is `bugfix`, then: `git push
602-
--force-with-lease origin master:bugfix`. Don't close the PR. It will close
603-
after you push it upstream. It will have the purple merged status rather than
604-
the red closed status. If you close the PR before GitHub adjusts its status, it
605-
will show up as a 0 commit PR with no changed files. The order of operations is
606-
important. If you push upstream before you push to your branch, GitHub will
607-
close the issue with the red closed status.
603+
--force-with-lease origin master:bugfix`. Don't close the pull request.
604+
It will close after you push it upstream. It will have the purple merged
605+
status rather than the red closed status. If you close the pull request
606+
before GitHub adjusts its status, it will show up as a 0 commit pull
607+
request with no changed files. The order of operations is important.
608+
If you push upstream before you push to your branch, GitHub will close
609+
the issue with the red closed status.
608610

609611
Time to push it:
610612

@@ -645,7 +647,7 @@ git push upstream master
645647
### I Made a Mistake
646648

647649
* Ping a TSC member.
648-
* `#node-dev` on freenode
650+
* `#node-dev` on freenode.
649651
* With `git`, there's a way to override remote trees by force pushing
650652
(`git push -f`). This is generally forbidden as it creates conflicts in other
651653
people's forks. It is permissible for simpler slip-ups such as typos in commit
@@ -701,8 +703,8 @@ land on the staging branches, the backporter removes the `lts-watch-` label.
701703
Likewise, as commits land in an LTS release, the releaser removes the `land-on-`
702704
label.
703705

704-
Attach the appropriate `lts-watch-` label to any PR that may impact an LTS
705-
release.
706+
Attach the appropriate `lts-watch-` label to any pull request that
707+
may impact an LTS release.
706708

707709
## Who to CC in the issue tracker
708710

‎doc/guides/cpp-style-guide.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,13 @@ runtime features.
4040

4141
Coding guidelines are based on the following guides (highest priority first):
4242

43-
1. This document
44-
2. The [Google C++ Style Guide][]
45-
3. The ISO [C++ Core Guidelines][]
43+
1. This document.
44+
2. The [Google C++ Style Guide][].
45+
3. The ISO [C++ Core Guidelines][].
4646

47-
In general code should follow the C++ Core Guidelines, unless overridden by the
47+
In general, code should follow the C++ Core Guidelines, unless overridden by the
4848
Google C++ Style Guide or this document. At the moment these guidelines are
49-
checked manually by reviewers, with the goal to validate this with automatic
49+
checked manually by reviewers with the goal to validate this with automatic
5050
tools.
5151

5252
## Formatting
@@ -282,11 +282,11 @@ data[0] = 12345;
282282

283283
### Type casting
284284

285-
* Use `static_cast<T>` if casting is required, and it is valid
286-
* Use `reinterpret_cast` only when it is necessary
287-
* Avoid C-style casts (`(type)value`)
285+
* Use `static_cast<T>` if casting is required, and it is valid.
286+
* Use `reinterpret_cast` only when it is necessary.
287+
* Avoid C-style casts (`(type)value`).
288288
* `dynamic_cast` does not work because Node.js is built without
289-
[Run Time Type Information][]
289+
[Run Time Type Information][].
290290

291291
Further reading:
292292

@@ -313,13 +313,13 @@ for (const auto& item : some_map) {
313313

314314
### Do not include `*.h` if `*-inl.h` has already been included
315315

316-
Do
316+
Do:
317317

318318
```cpp
319319
#include "util-inl.h" // already includes util.h
320320
```
321321

322-
instead of
322+
Instead of:
323323

324324
```cpp
325325
#include "util.h"
@@ -383,9 +383,9 @@ exports.foo = function(str) {
383383
#### Avoid throwing JavaScript errors in nested C++ methods
384384

385385
When you need to throw a JavaScript exception from C++ (i.e.
386-
`isolate()->ThrowException()`) prefer to do it as close to the return to JS as
387-
possible, and not inside of nested C++ calls. Since this changes the JS
388-
execution state doing it closest to where it is consumed reduces the chances of
386+
`isolate()->ThrowException()`), do it as close to the return to JavaScript as
387+
possible, and not inside of nested C++ calls. Since this changes the JavaScript
388+
execution state, doing it closest to where it is consumed reduces the chances of
389389
side effects.
390390

391391
Node.js is built [without C++ exception handling][], so code using `throw` or

‎doc/guides/cve-management-process.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ than two remaining CVEs a new block must be requested as follows:
6363
to the Available list.
6464

6565
All changes to the files for managing CVEs in a given year will
66-
be done through Pull Requests so that we have a record of how
66+
be done through pull requests so that we have a record of how
6767
the CVEs have been assigned.
6868

6969
CVEs are only valid for a specific year. At the beginning of each
@@ -122,7 +122,7 @@ following steps are used to assign, announce and report a CVE.
122122
verification of the identity of the CVE submitter.
123123

124124
For each CVE listed, the additional data must include the following fields
125-
updated with appropriate data for the CVE
125+
updated with appropriate data for the CVE:
126126
```text
127127
[CVEID]: CVE-XXXX-XXXX
128128
[PRODUCT]: Node.js

‎doc/guides/maintaining-openssl.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@
33
This document describes how to update `deps/openssl/`.
44

55
## Requirements
6-
* Linux environment
6+
* Linux environment.
77
* `perl` Only Perl version 5 is tested.
8-
* `nasm` (<http://www.nasm.us/>) The version of 2.11 or higher is needed.
9-
* GNU `as` in binutils. The version of 2.26 or higher is needed.
8+
* `nasm` (<http://www.nasm.us/>) Version 2.11 or higher is needed.
9+
* GNU `as` in binutils. Version 2.26 or higher is needed.
1010

1111
## 0. Check Requirements
1212

@@ -39,7 +39,8 @@ them.
3939
% git commit openssl
4040
````
4141

42-
The commit message can be (with the openssl version set to the relevant value):
42+
The commit message can be written as (with the openssl version set
43+
to the relevant value):
4344
```text
4445
deps: upgrade openssl sources to 1.1.0h
4546
@@ -62,15 +63,15 @@ Use `make` to regenerate all platform dependent files in
6263

6364
## 3. Check diffs
6465

65-
Check diffs if updates are right. Even if no updates in openssl
66-
sources, `buildinf.h` files will be updated for they have a timestamp
66+
Check diffs to ensure updates are right. Even if there are no updates in openssl
67+
sources, `buildinf.h` files will be updated because they have timestamp
6768
data in them.
6869
```sh
6970
% git diff -- deps/openssl
7071
```
7172

72-
*Note*: On Windows, OpenSSL Configure generates `makefile` that can be
73-
used for `nmake` command. The `make` command in the step 2 above uses
73+
*Note*: On Windows, OpenSSL Configure generates a `makefile` that can be
74+
used for the `nmake` command. The `make` command in step 2 (above) uses
7475
`Makefile_VC-WIN64A` and `Makefile_VC-WIN32` that are manually
7576
created. When source files or build options are updated in Windows,
7677
it needs to change these two Makefiles by hand. If you are not sure,
@@ -79,7 +80,7 @@ please ask @shigeki for details.
7980
## 4. Commit and make test
8081

8182
Update all architecture dependent files. Do not forget to git add or remove
82-
files if they are changed before commit:
83+
files if they are changed before committing:
8384
```sh
8485
% git add deps/openssl/config/archs
8586
% git add deps/openssl/openssl/include/crypto/bn_conf.h
@@ -88,7 +89,8 @@ files if they are changed before commit:
8889
% git commit
8990
```
9091

91-
The commit message can be (with the openssl version set to the relevant value):
92+
The commit message can be written as (with the openssl version set
93+
to the relevant value):
9294
```text
9395
deps: update archs files for OpenSSL-1.1.0
9496
@@ -102,4 +104,4 @@ The commit message can be (with the openssl version set to the relevant value):
102104
$ git commit
103105
```
104106

105-
Finally, build Node.js and run tests.
107+
Finally, build Node.js and run the tests.

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL