Skip to content

Commit fb7afb9

Browse files
Trotttargos
Trott
authored and
targos
committed
doc: format doc/guides using format-md task
PR-URL: #40358 Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
1 parent 5668182 commit fb7afb9

23 files changed

+426
-368
lines changed

‎doc/guides/backporting-to-release-lines.md‎

Lines changed: 35 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -32,58 +32,65 @@ branch. In order to submit a backport pull request to another branch, simply
3232
replace that with the staging branch for the targeted release line.
3333

3434
1. Checkout the staging branch for the targeted release line.
35+
3536
2. Make sure that the local staging branch is up to date with the remote.
37+
3638
3. Create a new branch off of the staging branch, as shown below.
3739

38-
```bash
39-
# Assuming your fork of Node.js is checked out in $NODE_DIR,
40-
# the origin remote points to your fork, and the upstream remote points
41-
# to git://github.com/nodejs/node
42-
cd $NODE_DIR
43-
# If v10.x-staging is checked out `pull` should be used instead of `fetch`
44-
git fetch upstream v10.x-staging:v10.x-staging -f
45-
# Assume we want to backport PR #10157
46-
git checkout -b backport-10157-to-v10.x v10.x-staging
47-
# Ensure there are no test artifacts from previous builds
48-
# Note that this command deletes all files and directories
49-
# not under revision control below the ./test directory.
50-
# It is optional and should be used with caution.
51-
git clean -xfd ./test/
52-
```
40+
```bash
41+
# Assuming your fork of Node.js is checked out in $NODE_DIR,
42+
# the origin remote points to your fork, and the upstream remote points
43+
# to git://github.com/nodejs/node
44+
cd $NODE_DIR
45+
# If v10.x-staging is checked out `pull` should be used instead of `fetch`
46+
git fetch upstream v10.x-staging:v10.x-staging -f
47+
# Assume we want to backport PR #10157
48+
git checkout -b backport-10157-to-v10.x v10.x-staging
49+
# Ensure there are no test artifacts from previous builds
50+
# Note that this command deletes all files and directories
51+
# not under revision control below the ./test directory.
52+
# It is optional and should be used with caution.
53+
git clean -xfd ./test/
54+
```
5355

5456
4. After creating the branch, apply the changes to the branch. The cherry-pick
5557
will likely fail due to conflicts. In that case, you will see something
5658
like this:
5759

58-
```console
59-
# Say the $SHA is 773cdc31ef
60-
$ git cherry-pick $SHA # Use your commit hash
61-
error: could not apply 773cdc3... <commit title>
62-
hint: after resolving the conflicts, mark the corrected paths
63-
hint: with 'git add <paths>' or 'git rm <paths>'
64-
hint: and commit the result with 'git commit'
65-
```
60+
```console
61+
# Say the $SHA is 773cdc31ef
62+
$ git cherry-pick $SHA # Use your commit hash
63+
error: could not apply 773cdc3... <commit title>
64+
hint: after resolving the conflicts, mark the corrected paths
65+
hint: with 'git add <paths>' or 'git rm <paths>'
66+
hint: and commit the result with 'git commit'
67+
```
6668

6769
5. Make the required changes to remove the conflicts, add the files to the index
6870
using `git add`, and then commit the changes. That can be done with
6971
`git cherry-pick --continue`.
72+
7073
6. Leave the commit message as is. If you think it should be modified, comment
7174
in the pull request. The `Backport-PR-URL` metadata does need to be added to
7275
the commit, but this will be done later.
76+
7377
7. Make sure `make -j4 test` passes.
78+
7479
8. Push the changes to your fork.
80+
7581
9. Open a pull request:
7682
1. Be sure to target the `v10.x-staging` branch in the pull request.
77-
1. Include the backport target in the pull request title in the following
83+
2. Include the backport target in the pull request title in the following
7884
format: `[v10.x backport] <commit title>`.
7985
Example: `[v10.x backport] process: improve performance of nextTick`
80-
1. Check the checkbox labeled "Allow edits and access to secrets by
86+
3. Check the checkbox labeled "Allow edits and access to secrets by
8187
maintainers".
82-
1. In the description add a reference to the original pull request.
83-
1. Amend the commit message and include a `Backport-PR-URL:` metadata and
88+
4. In the description add a reference to the original pull request.
89+
5. Amend the commit message and include a `Backport-PR-URL:` metadata and
8490
re-push the change to your fork.
85-
1. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the
91+
6. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the
8692
default `<pr base branch>`)
93+
8794
10. If during the review process conflicts arise, use the following to rebase:
8895
`git pull --rebase upstream v10.x-staging`
8996

‎doc/guides/collaborator-guide.md‎

Lines changed: 73 additions & 73 deletions
Large diffs are not rendered by default.

‎doc/guides/commit-queue.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
> Stability: 1 - Experimental
44
5-
*tl;dr: You can land pull requests by adding the `commit-queue` label to it.*
5+
_tl;dr: You can land pull requests by adding the `commit-queue` label to it._
66

77
Commit Queue is an experimental feature for the project which simplifies the
88
landing process by automating it via GitHub Actions. With it, collaborators can
@@ -58,17 +58,17 @@ events every five minutes. Five minutes is the smallest number accepted by
5858
the scheduler. The scheduler is not guaranteed to run every five minutes, it
5959
might take longer between runs.
6060

61-
Using the scheduler is preferable over using pull_request_target for two
61+
Using the scheduler is preferable over using pull\_request\_target for two
6262
reasons:
6363

6464
1. if two Commit Queue Actions execution overlap, there's a high-risk that
6565
the last one to finish will fail because the local branch will be out of
6666
sync with the remote after the first Action pushes. `issue_comment` event
6767
has the same limitation.
6868
2. `pull_request_target` will only run if the Action exists on the base commit
69-
of a pull request, and it will run the Action version present on that
70-
commit, meaning we wouldn't be able to use it for already opened PRs
71-
without rebasing them first.
69+
of a pull request, and it will run the Action version present on that
70+
commit, meaning we wouldn't be able to use it for already opened PRs
71+
without rebasing them first.
7272

7373
`node-core-utils` is configured with a personal token and
7474
a Jenkins token from
@@ -79,16 +79,16 @@ that into a list of PR ids we can pass as arguments to
7979
[`commit-queue.sh`](../../tools/actions/commit-queue.sh).
8080

8181
> The personal token only needs permission for public repositories and to read
82-
> profiles, we can use the GITHUB_TOKEN for write operations. Jenkins token is
82+
> profiles, we can use the GITHUB\_TOKEN for write operations. Jenkins token is
8383
> required to check CI status.
8484
8585
`commit-queue.sh` receives the following positional arguments:
8686

8787
1. The repository owner
8888
2. The repository name
89-
3. The Action GITHUB_TOKEN
89+
3. The Action GITHUB\_TOKEN
9090
4. Every positional argument starting at this one will be a pull request ID of
91-
a pull request with commit-queue set.
91+
a pull request with commit-queue set.
9292

9393
The script will iterate over the pull requests. `ncu-ci` is used to check if
9494
the last CI is still pending, and calls to the GitHub API are used to check if

‎doc/guides/contributing/code-of-conduct.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Code of Conduct
22

3-
The Node.js project has a [Code of Conduct][] that *all* contributors are
4-
expected to follow. This code describes the *minimum* behavior expectations
3+
The Node.js project has a [Code of Conduct][] that _all_ contributors are
4+
expected to follow. This code describes the _minimum_ behavior expectations
55
for all contributors.
66

77
As a contributor to Node.js, how you choose to act and interact towards your
@@ -12,7 +12,7 @@ allows anyone and everyone who wants to contribute to feel safe doing so.
1212

1313
Should any individual act in any way that is considered in violation of the
1414
[Code of Conduct][], corrective actions will be taken. It is possible, however,
15-
for any individual to *act* in such a manner that is not in violation of the
15+
for any individual to _act_ in such a manner that is not in violation of the
1616
strict letter of the Code of Conduct guidelines while still going completely
1717
against the spirit of what that Code is intended to accomplish.
1818

@@ -26,17 +26,17 @@ All contributors to Node.js tacitly agree to abide by both the letter and
2626
spirit of the [Code of Conduct][]. Failure, or unwillingness, to do so will
2727
result in contributions being respectfully declined.
2828

29-
A *bad actor* is someone who repeatedly violates the spirit of the Code of
29+
A _bad actor_ is someone who repeatedly violates the spirit of the Code of
3030
Conduct through failure to regulate how they
3131
interact with others. In doing so, bad actors
3232
alienate other contributors, discourage collaboration, and generally reflect
3333
poorly on the project as a whole.
3434

3535
Being a bad actor may be intentional or unintentional. Typically, unintentional
3636
bad behavior can be easily corrected by being quick to apologize and correct
37-
course *even if you are not entirely convinced you need to*. Giving other
37+
course _even if you are not entirely convinced you need to_. Giving other
3838
contributors the benefit of the doubt and having a sincere willingness to admit
39-
that you *might* be wrong is critical for any successful open collaboration.
39+
that you _might_ be wrong is critical for any successful open collaboration.
4040

4141
Don't be a bad actor.
4242

‎doc/guides/contributing/issues.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ test case we can use to recreate the problem on our own. If we cannot recreate
3030
the issue, it becomes impossible for us to fix.
3131

3232
In order to rule out the possibility of bugs introduced by userland code, test
33-
cases should be limited, as much as possible, to using *only* Node.js APIs.
33+
cases should be limited, as much as possible, to using _only_ Node.js APIs.
3434
If the bug occurs only when you're using a specific userland module, there is
3535
a very good chance that either (a) the module has a bug or (b) something in
3636
Node.js changed that broke the module.
@@ -53,7 +53,7 @@ project's GitHub organization plus a few contributions to the project
5353
(commenting on issues or PRs) can apply for and become a triager. Open a PR
5454
on the README.md of this project with: i) a request to be added as a triager,
5555
ii) the motivation for becoming a triager, and iii) agreement on reading,
56-
understanding, and adhering to the project's [Code Of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md).
56+
understanding, and adhering to the project's [Code Of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE\_OF\_CONDUCT.md).
5757

5858
The triage role enables the ability to carry out the most common triage
5959
activities, such as applying labels and closing/reopening/assigning issues.

‎doc/guides/contributing/pull-requests.md‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434

3535
## Dependencies
3636

37-
Node.js has several bundled dependencies in the *deps/* and the *tools/*
37+
Node.js has several bundled dependencies in the _deps/_ and the _tools/_
3838
directories that are not part of the project proper. Changes to files in those
3939
directories should be sent to their respective projects. Do not send a patch to
4040
Node.js. We cannot accept such patches.
@@ -161,33 +161,37 @@ notes about [commit squashing](#commit-squashing).
161161
A good commit message should describe what changed and why.
162162

163163
1. The first line should:
164+
164165
* contain a short description of the change (preferably 50 characters or
165166
less, and no more than 72 characters)
166167
* be entirely in lowercase with the exception of proper nouns, acronyms, and
167-
the words that refer to code, like function/variable names
168+
the words that refer to code, like function/variable names
168169
* be prefixed with the name of the changed [subsystem](#appendix-subsystems)
169-
and start with an imperative verb. Check the output of `git log --oneline
170-
files/you/changed` to find out what subsystems your changes touch.
170+
and start with an imperative verb. Check the output of `git log --oneline
171+
files/you/changed` to find out what subsystems your changes touch.
171172

172173
Examples:
174+
173175
* `net: add localAddress and localPort to Socket`
174176
* `src: fix typos in async_wrap.h`
175177

176178
2. Keep the second line blank.
179+
177180
3. Wrap all other lines at 72 columns (except for long URLs).
178181

179182
4. If your patch fixes an open issue, you can add a reference to it at the end
180183
of the log. Use the `Fixes:` prefix and the full issue URL. For other
181184
references use `Refs:`.
182185

183186
Examples:
187+
184188
* `Fixes: https://github.com/nodejs/node/issues/1337`
185189
* `Refs: https://eslint.org/docs/rules/space-in-parens.html`
186190
* `Refs: https://github.com/nodejs/node/pull/3615`
187191

188192
5. If your commit introduces a breaking change (`semver-major`), it should
189-
contain an explanation about the reason of the breaking change, which
190-
situation would trigger the breaking change and what is the exact change.
193+
contain an explanation about the reason of the breaking change, which
194+
situation would trigger the breaking change and what is the exact change.
191195

192196
Sample complete commit message:
193197

@@ -322,7 +326,7 @@ reviews a pull request they may find specific details that they would like to
322326
see changed or fixed. These may be as simple as fixing a typo, or may involve
323327
substantive changes to the code you have written. While such requests are
324328
intended to be helpful, they may come across as abrupt or unhelpful, especially
325-
requests to change things that do not include concrete suggestions on *how* to
329+
requests to change things that do not include concrete suggestions on _how_ to
326330
change them.
327331

328332
Try not to be discouraged. If you feel that a particular review is unfair,
@@ -384,7 +388,7 @@ Focus first on the most significant aspects of the change:
384388
4. Is the commit message readable and correct? If it contains a breaking change
385389
is it clear enough?
386390

387-
When changes are necessary, *request* them, do not *demand* them, and do not
391+
When changes are necessary, _request_ them, do not _demand_ them, and do not
388392
assume that the submitter already knows how to add a test or run a benchmark.
389393

390394
Specific performance optimization techniques, coding styles and conventions
@@ -404,7 +408,7 @@ with the appropriate reason to keep the conversation flow concise and relevant.
404408

405409
### Be aware of the person behind the code
406410

407-
Be aware that *how* you communicate requests and reviews in your feedback can
411+
Be aware that _how_ you communicate requests and reviews in your feedback can
408412
have a significant impact on the success of the pull request. Yes, we may land
409413
a particular change that makes Node.js better, but the individual might just
410414
not want to have anything to do with Node.js ever again. The goal is not just
@@ -446,7 +450,7 @@ or by leaving an `LGTM` ("Looks Good To Me") comment.
446450
When explicitly using the "Changes requested" component of the GitHub Approval
447451
Workflow, show empathy. That is, do not be rude or abrupt with your feedback
448452
and offer concrete suggestions for improvement, if possible. If you're not
449-
sure *how* a particular change can be improved, say so.
453+
sure _how_ a particular change can be improved, say so.
450454

451455
Most importantly, after leaving such requests, it is courteous to make yourself
452456
available later to check whether your comments have been addressed.
@@ -494,7 +498,7 @@ changing working functional code just for the sake of changing.
494498

495499
If a particular pull request introduces a performance or functional
496500
regression, rather than simply rejecting the pull request, take the time to
497-
work *with* the contributor on improving the change. Offer feedback and
501+
work _with_ the contributor on improving the change. Offer feedback and
498502
advice on what would make the pull request acceptable, and do not assume that
499503
the contributor should already know how to do that. Be explicit in your
500504
feedback.

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ Node.js codebase not related to stylistic issues.
1414
* [Align function arguments vertically](#align-function-arguments-vertically)
1515
* [Initialization lists](#initialization-lists)
1616
* [CamelCase for methods, functions, and classes](#camelcase-for-methods-functions-and-classes)
17-
* [`snake_case` for local variables and parameters](#snake_case-for-local-variables-and-parameters)
18-
* [`snake_case_` for private class fields](#snake_case_-for-private-class-fields)
19-
* [`snake_case` for C-like structs](#snake_case-for-c-like-structs)
17+
* [`snake_case` for local variables and parameters](#snake\_case-for-local-variables-and-parameters)
18+
* [`snake_case_` for private class fields](#snake\_case\_-for-private-class-fields)
19+
* [`snake_case` for C-like structs](#snake\_case-for-c-like-structs)
2020
* [Space after `template`](#space-after-template)
2121
* [Memory management](#memory-management)
2222
* [Memory allocation](#memory-allocation)
@@ -174,7 +174,7 @@ class Foo {
174174

175175
### `snake_case` for C-like structs
176176

177-
For plain C-like structs snake_case can be used.
177+
For plain C-like structs snake\_case can be used.
178178

179179
```cpp
180180
struct foo_bar {
@@ -267,7 +267,8 @@ class ExampleClass {
267267

268268
When working with typed arrays that involve direct data modification
269269
from C++, use an `AliasedBuffer` when possible. The API abstraction and
270-
the usage scope of `AliasedBuffer` are documented in [aliased_buffer.h][].
270+
the usage scope of `AliasedBuffer` are documented in
271+
[aliased\_buffer.h][aliased_buffer.h].
271272

272273
```cpp
273274
// Create an AliasedBuffer.

0 commit comments

Comments
 (0)