GeezerVison is showing github.com — doc: format doc/guides using format-md task · nodejs/node@eb65871
File treeExpand file treeCollapse file tree Open diff view settings Expand file treeCollapse file tree Open diff view settings Collapse file Copy file name to clipboardExpand all lines: doc/guides/backporting-to-release-lines.md +35-28Lines changed: 35 additions & 28 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -32,58 +32,65 @@ branch. In order to submit a backport pull request to another branch, simply | 32 | 32 | replace that with the staging branch for the targeted release line. | 33 | 33 |
| 34 | 34 | 1. Checkout the staging branch for the targeted release line. | | 35 | + | 35 | 36 | 2. Make sure that the local staging branch is up to date with the remote. | | 37 | + | 36 | 38 | 3. Create a new branch off of the staging branch, as shown below. | 37 | 39 |
| 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 | + ``` | 53 | 55 |
| 54 | 56 | 4. After creating the branch, apply the changes to the branch. The cherry-pick | 55 | 57 | will likely fail due to conflicts. In that case, you will see something | 56 | 58 | like this: | 57 | 59 |
| 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 | + ``` | 66 | 68 |
| 67 | 69 | 5. Make the required changes to remove the conflicts, add the files to the index | 68 | 70 | using `git add`, and then commit the changes. That can be done with | 69 | 71 | `git cherry-pick --continue`. | | 72 | + | 70 | 73 | 6. Leave the commit message as is. If you think it should be modified, comment | 71 | 74 | in the pull request. The `Backport-PR-URL` metadata does need to be added to | 72 | 75 | the commit, but this will be done later. | | 76 | + | 73 | 77 | 7. Make sure `make -j4 test` passes. | | 78 | + | 74 | 79 | 8. Push the changes to your fork. | | 80 | + | 75 | 81 | 9. Open a pull request: | 76 | 82 | 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 | 78 | 84 | format: `[v10.x backport] <commit title>`. | 79 | 85 | 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 | 81 | 87 | 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 | 84 | 90 | 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 | 86 | 92 | default `<pr base branch>`) | | 93 | + | 87 | 94 | 10. If during the review process conflicts arise, use the following to rebase: | 88 | 95 | `git pull --rebase upstream v10.x-staging` | 89 | 96 |
| |
Collapse file Copy file name to clipboardExpand all lines: doc/guides/collaborator-guide.md +73-73Lines changed: 73 additions & 73 deletions - Display the source diff
- Display the rich diff
Large diffs are not rendered by default. Collapse file Copy file name to clipboardExpand all lines: doc/guides/commit-queue.md +8-8Lines changed: 8 additions & 8 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
| 2 | 2 |
| 3 | 3 | > Stability: 1 - Experimental | 4 | 4 |
| 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._ | 6 | 6 |
| 7 | 7 | Commit Queue is an experimental feature for the project which simplifies the | 8 | 8 | 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 | 58 | 58 | the scheduler. The scheduler is not guaranteed to run every five minutes, it | 59 | 59 | might take longer between runs. | 60 | 60 |
| 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 | 62 | 62 | reasons: | 63 | 63 |
| 64 | 64 | 1. if two Commit Queue Actions execution overlap, there's a high-risk that | 65 | 65 | the last one to finish will fail because the local branch will be out of | 66 | 66 | sync with the remote after the first Action pushes. `issue_comment` event | 67 | 67 | has the same limitation. | 68 | 68 | 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. | 72 | 72 |
| 73 | 73 | `node-core-utils` is configured with a personal token and | 74 | 74 | a Jenkins token from | @@ -79,16 +79,16 @@ that into a list of PR ids we can pass as arguments to | 79 | 79 | [`commit-queue.sh`](../../tools/actions/commit-queue.sh). | 80 | 80 |
| 81 | 81 | > 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 | 83 | 83 | > required to check CI status. | 84 | 84 |
| 85 | 85 | `commit-queue.sh` receives the following positional arguments: | 86 | 86 |
| 87 | 87 | 1. The repository owner | 88 | 88 | 2. The repository name | 89 | | -3. The Action GITHUB_TOKEN | | 89 | +3. The Action GITHUB\_TOKEN | 90 | 90 | 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. | 92 | 92 |
| 93 | 93 | The script will iterate over the pull requests. `ncu-ci` is used to check if | 94 | 94 | the last CI is still pending, and calls to the GitHub API are used to check if | |
Collapse file Copy file name to clipboardExpand all lines: doc/guides/contributing/code-of-conduct.md +6-6Lines changed: 6 additions & 6 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
| 1 | 1 | # Code of Conduct | 2 | 2 |
| 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 | 5 | 5 | for all contributors. | 6 | 6 |
| 7 | 7 | 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. | 12 | 12 |
| 13 | 13 | Should any individual act in any way that is considered in violation of the | 14 | 14 | [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 | 16 | 16 | strict letter of the Code of Conduct guidelines while still going completely | 17 | 17 | against the spirit of what that Code is intended to accomplish. | 18 | 18 |
| @@ -26,17 +26,17 @@ All contributors to Node.js tacitly agree to abide by both the letter and | 26 | 26 | spirit of the [Code of Conduct][]. Failure, or unwillingness, to do so will | 27 | 27 | result in contributions being respectfully declined. | 28 | 28 |
| 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 | 30 | 30 | Conduct through failure to regulate how they | 31 | 31 | interact with others. In doing so, bad actors | 32 | 32 | alienate other contributors, discourage collaboration, and generally reflect | 33 | 33 | poorly on the project as a whole. | 34 | 34 |
| 35 | 35 | Being a bad actor may be intentional or unintentional. Typically, unintentional | 36 | 36 | 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 | 38 | 38 | 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. | 40 | 40 |
| 41 | 41 | Don't be a bad actor. | 42 | 42 |
| |
Collapse file Copy file name to clipboardExpand all lines: doc/guides/contributing/issues.md +2-2Lines changed: 2 additions & 2 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -30,7 +30,7 @@ test case we can use to recreate the problem on our own. If we cannot recreate | 30 | 30 | the issue, it becomes impossible for us to fix. | 31 | 31 |
| 32 | 32 | 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. | 34 | 34 | If the bug occurs only when you're using a specific userland module, there is | 35 | 35 | a very good chance that either (a) the module has a bug or (b) something in | 36 | 36 | Node.js changed that broke the module. | @@ -53,7 +53,7 @@ project's GitHub organization plus a few contributions to the project | 53 | 53 | (commenting on issues or PRs) can apply for and become a triager. Open a PR | 54 | 54 | on the README.md of this project with: i) a request to be added as a triager, | 55 | 55 | 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). | 57 | 57 |
| 58 | 58 | The triage role enables the ability to carry out the most common triage | 59 | 59 | activities, such as applying labels and closing/reopening/assigning issues. | |
Collapse file Copy file name to clipboardExpand all lines: doc/guides/contributing/pull-requests.md +15-11Lines changed: 15 additions & 11 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
| 34 | 34 |
| 35 | 35 | ## Dependencies | 36 | 36 |
| 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/_ | 38 | 38 | directories that are not part of the project proper. Changes to files in those | 39 | 39 | directories should be sent to their respective projects. Do not send a patch to | 40 | 40 | Node.js. We cannot accept such patches. | @@ -161,33 +161,37 @@ notes about [commit squashing](#commit-squashing). | 161 | 161 | A good commit message should describe what changed and why. | 162 | 162 |
| 163 | 163 | 1. The first line should: | | 164 | + | 164 | 165 | * contain a short description of the change (preferably 50 characters or | 165 | 166 | less, and no more than 72 characters) | 166 | 167 | * 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 | 168 | 169 | * 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. | 171 | 172 |
| 172 | 173 | Examples: | | 174 | + | 173 | 175 | * `net: add localAddress and localPort to Socket` | 174 | 176 | * `src: fix typos in async_wrap.h` | 175 | 177 |
| 176 | 178 | 2. Keep the second line blank. | | 179 | + | 177 | 180 | 3. Wrap all other lines at 72 columns (except for long URLs). | 178 | 181 |
| 179 | 182 | 4. If your patch fixes an open issue, you can add a reference to it at the end | 180 | 183 | of the log. Use the `Fixes:` prefix and the full issue URL. For other | 181 | 184 | references use `Refs:`. | 182 | 185 |
| 183 | 186 | Examples: | | 187 | + | 184 | 188 | * `Fixes: https://github.com/nodejs/node/issues/1337` | 185 | 189 | * `Refs: https://eslint.org/docs/rules/space-in-parens.html` | 186 | 190 | * `Refs: https://github.com/nodejs/node/pull/3615` | 187 | 191 |
| 188 | 192 | 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. | 191 | 195 |
| 192 | 196 | Sample complete commit message: | 193 | 197 |
| @@ -322,7 +326,7 @@ reviews a pull request they may find specific details that they would like to | 322 | 326 | see changed or fixed. These may be as simple as fixing a typo, or may involve | 323 | 327 | substantive changes to the code you have written. While such requests are | 324 | 328 | 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 | 326 | 330 | change them. | 327 | 331 |
| 328 | 332 | 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: | 384 | 388 | 4. Is the commit message readable and correct? If it contains a breaking change | 385 | 389 | is it clear enough? | 386 | 390 |
| 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 | 388 | 392 | assume that the submitter already knows how to add a test or run a benchmark. | 389 | 393 |
| 390 | 394 | Specific performance optimization techniques, coding styles and conventions | @@ -404,7 +408,7 @@ with the appropriate reason to keep the conversation flow concise and relevant. | 404 | 408 |
| 405 | 409 | ### Be aware of the person behind the code | 406 | 410 |
| 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 | 408 | 412 | have a significant impact on the success of the pull request. Yes, we may land | 409 | 413 | a particular change that makes Node.js better, but the individual might just | 410 | 414 | 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. | 446 | 450 | When explicitly using the "Changes requested" component of the GitHub Approval | 447 | 451 | Workflow, show empathy. That is, do not be rude or abrupt with your feedback | 448 | 452 | 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. | 450 | 454 |
| 451 | 455 | Most importantly, after leaving such requests, it is courteous to make yourself | 452 | 456 | available later to check whether your comments have been addressed. | @@ -494,7 +498,7 @@ changing working functional code just for the sake of changing. | 494 | 498 |
| 495 | 499 | If a particular pull request introduces a performance or functional | 496 | 500 | 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 | 498 | 502 | advice on what would make the pull request acceptable, and do not assume that | 499 | 503 | the contributor should already know how to do that. Be explicit in your | 500 | 504 | feedback. | |
Collapse file Copy file name to clipboardExpand all lines: doc/guides/cpp-style-guide.md +6-5Lines changed: 6 additions & 5 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -14,9 +14,9 @@ Node.js codebase not related to stylistic issues. | 14 | 14 | * [Align function arguments vertically](#align-function-arguments-vertically) | 15 | 15 | * [Initialization lists](#initialization-lists) | 16 | 16 | * [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) | 20 | 20 | * [Space after `template`](#space-after-template) | 21 | 21 | * [Memory management](#memory-management) | 22 | 22 | * [Memory allocation](#memory-allocation) | @@ -174,7 +174,7 @@ class Foo { | 174 | 174 |
| 175 | 175 | ### `snake_case` for C-like structs | 176 | 176 |
| 177 | | -For plain C-like structs snake_case can be used. | | 177 | +For plain C-like structs snake\_case can be used. | 178 | 178 |
| 179 | 179 | ```cpp | 180 | 180 | struct foo_bar { | @@ -267,7 +267,8 @@ class ExampleClass { | 267 | 267 |
| 268 | 268 | When working with typed arrays that involve direct data modification | 269 | 269 | 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]. | 271 | 272 |
| 272 | 273 | ```cpp | 273 | 274 | // Create an AliasedBuffer. | |
|