From eb65871ab4ec6e73bf8febb7bd373c3f22857988 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 6 Oct 2021 21:40:23 -0700 Subject: [PATCH] doc: format doc/guides using format-md task MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/40358 Reviewed-By: Tobias Nießen Reviewed-By: James M Snell Reviewed-By: Luigi Pinca --- doc/guides/backporting-to-release-lines.md | 63 ++++--- doc/guides/collaborator-guide.md | 146 +++++++-------- doc/guides/commit-queue.md | 16 +- doc/guides/contributing/code-of-conduct.md | 12 +- doc/guides/contributing/issues.md | 4 +- doc/guides/contributing/pull-requests.md | 26 +-- doc/guides/cpp-style-guide.md | 11 +- .../diagnostic-tooling-support-tiers.md | 66 +++---- doc/guides/doc-style-guide.md | 13 +- .../investigating_native_memory_leak.md | 15 +- doc/guides/maintaining-V8.md | 43 +++-- doc/guides/maintaining-icu.md | 32 ++-- doc/guides/maintaining-openssl.md | 10 +- doc/guides/maintaining-root-certs.md | 172 +++++++++--------- doc/guides/maintaining-zlib.md | 2 + doc/guides/node-postmortem-support.md | 4 +- doc/guides/releases.md | 57 +++--- doc/guides/security-release-process.md | 46 ++--- doc/guides/strategic-initiatives.md | 34 ++-- doc/guides/technical-values.md | 10 + doc/guides/using-internal-errors.md | 1 + doc/guides/writing-and-running-benchmarks.md | 8 +- doc/guides/writing-tests.md | 3 +- 23 files changed, 426 insertions(+), 368 deletions(-) diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 5233173c882557..75e16f410b3f28 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -32,58 +32,65 @@ branch. In order to submit a backport pull request to another branch, simply replace that with the staging branch for the targeted release line. 1. Checkout the staging branch for the targeted release line. + 2. Make sure that the local staging branch is up to date with the remote. + 3. Create a new branch off of the staging branch, as shown below. - ```bash - # Assuming your fork of Node.js is checked out in $NODE_DIR, - # the origin remote points to your fork, and the upstream remote points - # to git://github.com/nodejs/node - cd $NODE_DIR - # If v10.x-staging is checked out `pull` should be used instead of `fetch` - git fetch upstream v10.x-staging:v10.x-staging -f - # Assume we want to backport PR #10157 - git checkout -b backport-10157-to-v10.x v10.x-staging - # Ensure there are no test artifacts from previous builds - # Note that this command deletes all files and directories - # not under revision control below the ./test directory. - # It is optional and should be used with caution. - git clean -xfd ./test/ - ``` + ```bash + # Assuming your fork of Node.js is checked out in $NODE_DIR, + # the origin remote points to your fork, and the upstream remote points + # to git://github.com/nodejs/node + cd $NODE_DIR + # If v10.x-staging is checked out `pull` should be used instead of `fetch` + git fetch upstream v10.x-staging:v10.x-staging -f + # Assume we want to backport PR #10157 + git checkout -b backport-10157-to-v10.x v10.x-staging + # Ensure there are no test artifacts from previous builds + # Note that this command deletes all files and directories + # not under revision control below the ./test directory. + # It is optional and should be used with caution. + git clean -xfd ./test/ + ``` 4. After creating the branch, apply the changes to the branch. The cherry-pick will likely fail due to conflicts. In that case, you will see something like this: - ```console - # Say the $SHA is 773cdc31ef - $ git cherry-pick $SHA # Use your commit hash - error: could not apply 773cdc3... - hint: after resolving the conflicts, mark the corrected paths - hint: with 'git add ' or 'git rm ' - hint: and commit the result with 'git commit' - ``` + ```console + # Say the $SHA is 773cdc31ef + $ git cherry-pick $SHA # Use your commit hash + error: could not apply 773cdc3... + hint: after resolving the conflicts, mark the corrected paths + hint: with 'git add ' or 'git rm ' + hint: and commit the result with 'git commit' + ``` 5. Make the required changes to remove the conflicts, add the files to the index using `git add`, and then commit the changes. That can be done with `git cherry-pick --continue`. + 6. Leave the commit message as is. If you think it should be modified, comment in the pull request. The `Backport-PR-URL` metadata does need to be added to the commit, but this will be done later. + 7. Make sure `make -j4 test` passes. + 8. Push the changes to your fork. + 9. Open a pull request: 1. Be sure to target the `v10.x-staging` branch in the pull request. - 1. Include the backport target in the pull request title in the following + 2. Include the backport target in the pull request title in the following format: `[v10.x backport] `. Example: `[v10.x backport] process: improve performance of nextTick` - 1. Check the checkbox labeled "Allow edits and access to secrets by + 3. Check the checkbox labeled "Allow edits and access to secrets by maintainers". - 1. In the description add a reference to the original pull request. - 1. Amend the commit message and include a `Backport-PR-URL:` metadata and + 4. In the description add a reference to the original pull request. + 5. Amend the commit message and include a `Backport-PR-URL:` metadata and re-push the change to your fork. - 1. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the + 6. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the default ``) + 10. If during the review process conflicts arise, use the following to rebase: `git pull --rebase upstream v10.x-staging` diff --git a/doc/guides/collaborator-guide.md b/doc/guides/collaborator-guide.md index dd4f6e853e41c8..e3d48c09c5338a 100644 --- a/doc/guides/collaborator-guide.md +++ b/doc/guides/collaborator-guide.md @@ -51,7 +51,7 @@ request. See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker). Always show courtesy to individuals submitting issues and pull requests. Be welcoming to first-time contributors, identified by the GitHub -![First-time contributor](../first_timer_badge.png) badge. +![First-time contributor](../first\_timer\_badge.png) badge. For first-time contributors, check if the commit author is the same as the pull request author. This way, once their pull request lands, GitHub will show them @@ -255,27 +255,27 @@ Windows and ARM platforms are only kept for seven days. #### Useful Jenkins CI jobs * [`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/) -is the CI job to test pull requests. It runs the `build-ci` and `test-ci` -targets on all supported platforms. + is the CI job to test pull requests. It runs the `build-ci` and `test-ci` + targets on all supported platforms. * [`citgm-smoker`](https://ci.nodejs.org/job/citgm-smoker/) -uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run -`npm install && npm test` on a large selection of common modules. This is -useful to check whether a change will cause breakage in the ecosystem. + uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run + `npm install && npm test` on a large selection of common modules. This is + useful to check whether a change will cause breakage in the ecosystem. * [`node-stress-single-test`](https://ci.nodejs.org/job/node-stress-single-test/) -can run a group of tests over and over on a specific platform. Use it to check -that the tests are reliable. + can run a group of tests over and over on a specific platform. Use it to check + that the tests are reliable. * [`node-test-commit-v8-linux`](https://ci.nodejs.org/job/node-test-commit-v8-linux/) -runs the standard V8 tests. Run it when updating V8 in Node.js or floating new -patches on V8. + runs the standard V8 tests. Run it when updating V8 in Node.js or floating new + patches on V8. * [`node-test-commit-custom-suites-freestyle`](https://ci.nodejs.org/job/node-test-commit-custom-suites-freestyle/) -enables customization of test suites and parameters. It can execute test suites -not used in other CI test runs (such as tests in the `internet` or `pummel` -directories). It can also make sure tests pass when provided with a flag not -used in other CI test runs (such as `--worker`). + enables customization of test suites and parameters. It can execute test + suites not used in other CI test runs (such as tests in the `internet` or + `pummel` directories). It can also make sure tests pass when provided with a + flag not used in other CI test runs (such as `--worker`). #### Starting a Jenkins CI job @@ -285,13 +285,13 @@ You generally need to enter only one or both of the following options in the form: * `GIT_REMOTE_REF`: Change to the remote portion of git refspec. -To specify the branch this way, `refs/heads/BRANCH` is used -(e.g. for `master` -> `refs/heads/master`). -For pull requests, it will look like `refs/pull/PR_NUMBER/head` -(e.g. for pull request #42 -> `refs/pull/42/head`). + To specify the branch this way, `refs/heads/BRANCH` is used + (e.g. for `master` -> `refs/heads/master`). + For pull requests, it will look like `refs/pull/PR_NUMBER/head` + (e.g. for pull request #42 -> `refs/pull/42/head`). * `REBASE_ONTO`: Change that to `origin/master` so the pull request gets rebased -onto master. This can especially be important for pull requests that have been -open a while. + onto master. This can especially be important for pull requests that have been + open a while. Look at the list of jobs on the left hand side under "Build History" and copy the link to the one you started (which will be the one on top, but click @@ -488,20 +488,20 @@ The TSC serves as the final arbiter where required. who wish to land their own pull requests will self-assign them. Sometimes, an author will delegate to someone else. If in doubt, ask the assignee whether it is okay to land. -1. Never use GitHub's green ["Merge pull request"][] button. Reasons for not +2. Never use GitHub's green ["Merge pull request"][] button. Reasons for not using the web interface button: * The "Create a merge commit" method will add an unnecessary merge commit. * The "Squash and merge" method will add metadata (the pull request #) to the commit title. If more than one author contributes to the pull request, squashing only keeps one author. * The "Rebase and merge" method has no way of adding metadata to the commit. -1. Make sure CI is complete and green. If the CI is not green, check for +3. Make sure CI is complete and green. If the CI is not green, check for unreliable tests and infrastructure failures. If there are not corresponding issues in the [node][unreliable tests] or [build](https://github.com/nodejs/build/issues) repositories, open new issues. Run a new CI any time someone pushes new code to the pull request. -1. Check that the commit message adheres to [commit message guidelines][]. -1. Add all necessary [metadata](#metadata) to commit messages before landing. If +4. Check that the commit message adheres to [commit message guidelines][]. +5. Add all necessary [metadata](#metadata) to commit messages before landing. If you are unsure exactly how to format the commit messages, use the commit log as a reference. See [this commit][commit-example] as an example. @@ -676,10 +676,10 @@ $ git rev-list upstream/master...HEAD | xargs core-validate-commit ``` Optional: For your own commits, force push the amended commit to the pull -request branch. If your branch name is `bugfix`, then: `git push ---force-with-lease origin master:bugfix`. Don't close the pull request. -It will close after you push it upstream. It will have the purple merged -status rather than the red closed status. If you close the pull request +request branch. If your branch name is `bugfix`, then: +`git push --force-with-lease origin master:bugfix`. Don't close the pull +request. It will close after you push it upstream. It will have the purple +merged status rather than the red closed status. If you close the pull request before GitHub adjusts its status, it will show up as a 0 commit pull request with no changed files. The order of operations is important. If you push upstream before you push to your branch, GitHub will close @@ -752,7 +752,7 @@ corresponding staging branch (v10.x-staging, v8.x-staging, etc.). Commits that land on master are cherry-picked to each staging branch as appropriate. If a change applies only to the LTS branch, open the pull request -against the *staging* branch. Commits from the staging branch land on the LTS +against the _staging_ branch. Commits from the staging branch land on the LTS branch only when a release is being prepared. They might land on the LTS branch in a different order than they do in staging. @@ -771,7 +771,7 @@ There are several LTS-related labels: branches. For example, `lts-watch-v10.x` would be for a change to consider for the `v10.x-staging` branch. -* `land-on-` are for pull requests that should land in a future v*.x +* `land-on-` are for pull requests that should land in a future v\*.x release. For example, `land-on-v10.x` would be for a change to land in Node.js 10.x. @@ -785,46 +785,46 @@ might impact an LTS release. ## Who to CC in the issue tracker -| Subsystem | Maintainers | -| --- | --- | -| `benchmark/*` | @nodejs/benchmarking, @mscdex | -| `doc/*`, `*.md` | @nodejs/documentation | -| `lib/assert` | @nodejs/assert | -| `lib/async_hooks` | @nodejs/async\_hooks for bugs/reviews (+ @nodejs/diagnostics for API) | -| `lib/buffer` | @nodejs/buffer | -| `lib/child_process` | @nodejs/child\_process | -| `lib/cluster` | @nodejs/cluster | -| `lib/{crypto,tls,https}` | @nodejs/crypto | -| `lib/dgram` | @nodejs/dgram | -| `lib/domains` | @nodejs/domains | -| `lib/fs`, `src/{fs,file}` | @nodejs/fs | -| `lib/{_}http{*}` | @nodejs/http | -| `lib/inspector.js`, `src/inspector_*` | @nodejs/v8-inspector | -| `lib/internal/bootstrap/*` | @nodejs/process | -| `lib/internal/url`, `src/node_url` | @nodejs/url | -| `lib/net` | @bnoordhuis, @indutny, @nodejs/streams | -| `lib/repl` | @nodejs/repl | -| `lib/{_}stream{*}` | @nodejs/streams | -| `lib/timers` | @nodejs/timers | -| `lib/util` | @nodejs/util | -| `lib/zlib` | @nodejs/zlib | -| `src/async_wrap.*` | @nodejs/async\_hooks | -| `src/node_api.*` | @nodejs/n-api | -| `src/node_crypto.*` | @nodejs/crypto | -| `test/*` | @nodejs/testing | -| `tools/node_modules/eslint`, `.eslintrc` | @nodejs/linting | -| build | @nodejs/build | -| `src/module_wrap.*`, `lib/internal/modules/*`, `lib/internal/vm/module.js` | @nodejs/modules | -| GYP | @nodejs/gyp | -| performance | @nodejs/performance | -| platform specific | @nodejs/platform-{aix,arm,freebsd,macos,ppc,smartos,s390,windows} | -| python code | @nodejs/python | -| upgrading c-ares | @rvagg | -| upgrading http-parser | @nodejs/http, @nodejs/http2 | -| upgrading libuv | @nodejs/libuv | -| upgrading npm | @nodejs/npm | -| upgrading V8 | @nodejs/V8, @nodejs/post-mortem | -| Embedded use or delivery of Node.js | @nodejs/delivery-channels | +| Subsystem | Maintainers | +| -------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| `benchmark/*` | @nodejs/benchmarking, @mscdex | +| `doc/*`, `*.md` | @nodejs/documentation | +| `lib/assert` | @nodejs/assert | +| `lib/async_hooks` | @nodejs/async\_hooks for bugs/reviews (+ @nodejs/diagnostics for API) | +| `lib/buffer` | @nodejs/buffer | +| `lib/child_process` | @nodejs/child\_process | +| `lib/cluster` | @nodejs/cluster | +| `lib/{crypto,tls,https}` | @nodejs/crypto | +| `lib/dgram` | @nodejs/dgram | +| `lib/domains` | @nodejs/domains | +| `lib/fs`, `src/{fs,file}` | @nodejs/fs | +| `lib/{_}http{*}` | @nodejs/http | +| `lib/inspector.js`, `src/inspector_*` | @nodejs/v8-inspector | +| `lib/internal/bootstrap/*` | @nodejs/process | +| `lib/internal/url`, `src/node_url` | @nodejs/url | +| `lib/net` | @bnoordhuis, @indutny, @nodejs/streams | +| `lib/repl` | @nodejs/repl | +| `lib/{_}stream{*}` | @nodejs/streams | +| `lib/timers` | @nodejs/timers | +| `lib/util` | @nodejs/util | +| `lib/zlib` | @nodejs/zlib | +| `src/async_wrap.*` | @nodejs/async\_hooks | +| `src/node_api.*` | @nodejs/n-api | +| `src/node_crypto.*` | @nodejs/crypto | +| `test/*` | @nodejs/testing | +| `tools/node_modules/eslint`, `.eslintrc` | @nodejs/linting | +| build | @nodejs/build | +| `src/module_wrap.*`, `lib/internal/modules/*`, `lib/internal/vm/module.js` | @nodejs/modules | +| GYP | @nodejs/gyp | +| performance | @nodejs/performance | +| platform specific | @nodejs/platform-{aix,arm,freebsd,macos,ppc,smartos,s390,windows} | +| python code | @nodejs/python | +| upgrading c-ares | @rvagg | +| upgrading http-parser | @nodejs/http, @nodejs/http2 | +| upgrading libuv | @nodejs/libuv | +| upgrading npm | @nodejs/npm | +| upgrading V8 | @nodejs/V8, @nodejs/post-mortem | +| Embedded use or delivery of Node.js | @nodejs/delivery-channels | When things need extra attention, are controversial, or `semver-major`: @nodejs/tsc @@ -843,7 +843,7 @@ If you cannot find who to cc for a file, `git shortlog -n -s ` can help. * `tsc-agenda`: Open issues and pull requests with this label will be added to the Technical Steering Committee meeting agenda ---- +*** * `author-ready` - A pull request is _author ready_ when: * There is a CI run in progress or completed. @@ -855,10 +855,10 @@ Please always add the `author ready` label to pull requests that qualify. Please always remove it again as soon as the conditions are not met anymore, such as if the CI run fails or a new outstanding review comment is posted. ---- +*** * `semver-{minor,major}` - * be conservative – that is, if a change has the remote *chance* of breaking + * be conservative – that is, if a change has the remote _chance_ of breaking something, go for semver-major * when adding a semver label, add a comment explaining why you're adding it * minor vs. patch: roughly: "does it add a new method / does it add a new diff --git a/doc/guides/commit-queue.md b/doc/guides/commit-queue.md index 6d81ee8e652d2c..dec153196ea30e 100644 --- a/doc/guides/commit-queue.md +++ b/doc/guides/commit-queue.md @@ -2,7 +2,7 @@ > Stability: 1 - Experimental -*tl;dr: You can land pull requests by adding the `commit-queue` label to it.* +_tl;dr: You can land pull requests by adding the `commit-queue` label to it._ Commit Queue is an experimental feature for the project which simplifies the landing process by automating it via GitHub Actions. With it, collaborators can @@ -58,7 +58,7 @@ events every five minutes. Five minutes is the smallest number accepted by the scheduler. The scheduler is not guaranteed to run every five minutes, it might take longer between runs. -Using the scheduler is preferable over using pull_request_target for two +Using the scheduler is preferable over using pull\_request\_target for two reasons: 1. if two Commit Queue Actions execution overlap, there's a high-risk that @@ -66,9 +66,9 @@ reasons: sync with the remote after the first Action pushes. `issue_comment` event has the same limitation. 2. `pull_request_target` will only run if the Action exists on the base commit - of a pull request, and it will run the Action version present on that - commit, meaning we wouldn't be able to use it for already opened PRs - without rebasing them first. + of a pull request, and it will run the Action version present on that + commit, meaning we wouldn't be able to use it for already opened PRs + without rebasing them first. `node-core-utils` is configured with a personal token and a Jenkins token from @@ -79,16 +79,16 @@ that into a list of PR ids we can pass as arguments to [`commit-queue.sh`](../../tools/actions/commit-queue.sh). > The personal token only needs permission for public repositories and to read -> profiles, we can use the GITHUB_TOKEN for write operations. Jenkins token is +> profiles, we can use the GITHUB\_TOKEN for write operations. Jenkins token is > required to check CI status. `commit-queue.sh` receives the following positional arguments: 1. The repository owner 2. The repository name -3. The Action GITHUB_TOKEN +3. The Action GITHUB\_TOKEN 4. Every positional argument starting at this one will be a pull request ID of - a pull request with commit-queue set. + a pull request with commit-queue set. The script will iterate over the pull requests. `ncu-ci` is used to check if the last CI is still pending, and calls to the GitHub API are used to check if diff --git a/doc/guides/contributing/code-of-conduct.md b/doc/guides/contributing/code-of-conduct.md index 9c3ad120b13d34..1332246e404b7f 100644 --- a/doc/guides/contributing/code-of-conduct.md +++ b/doc/guides/contributing/code-of-conduct.md @@ -1,7 +1,7 @@ # Code of Conduct -The Node.js project has a [Code of Conduct][] that *all* contributors are -expected to follow. This code describes the *minimum* behavior expectations +The Node.js project has a [Code of Conduct][] that _all_ contributors are +expected to follow. This code describes the _minimum_ behavior expectations for all contributors. 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. Should any individual act in any way that is considered in violation of the [Code of Conduct][], corrective actions will be taken. It is possible, however, -for any individual to *act* in such a manner that is not in violation of the +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. @@ -26,7 +26,7 @@ All contributors to Node.js tacitly agree to abide by both the letter and spirit of the [Code of Conduct][]. Failure, or unwillingness, to do so will result in contributions being respectfully declined. -A *bad actor* is someone who repeatedly violates the spirit of the Code of +A _bad actor_ is someone who repeatedly violates the spirit of the Code of Conduct through failure to regulate how they interact with others. In doing so, bad actors alienate other contributors, discourage collaboration, and generally reflect @@ -34,9 +34,9 @@ poorly on the project as a whole. Being a bad actor may be intentional or unintentional. Typically, unintentional bad behavior can be easily corrected by being quick to apologize and correct -course *even if you are not entirely convinced you need to*. Giving other +course _even if you are not entirely convinced you need to_. Giving other contributors the benefit of the doubt and having a sincere willingness to admit -that you *might* be wrong is critical for any successful open collaboration. +that you _might_ be wrong is critical for any successful open collaboration. Don't be a bad actor. diff --git a/doc/guides/contributing/issues.md b/doc/guides/contributing/issues.md index 10aa28201d9e0b..26c64b773bcf4a 100644 --- a/doc/guides/contributing/issues.md +++ b/doc/guides/contributing/issues.md @@ -30,7 +30,7 @@ test case we can use to recreate the problem on our own. If we cannot recreate the issue, it becomes impossible for us to fix. In order to rule out the possibility of bugs introduced by userland code, test -cases should be limited, as much as possible, to using *only* Node.js APIs. +cases should be limited, as much as possible, to using _only_ Node.js APIs. If the bug occurs only when you're using a specific userland module, there is a very good chance that either (a) the module has a bug or (b) something in Node.js changed that broke the module. @@ -53,7 +53,7 @@ project's GitHub organization plus a few contributions to the project (commenting on issues or PRs) can apply for and become a triager. Open a PR on the README.md of this project with: i) a request to be added as a triager, ii) the motivation for becoming a triager, and iii) agreement on reading, -understanding, and adhering to the project's [Code Of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md). +understanding, and adhering to the project's [Code Of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE\_OF\_CONDUCT.md). The triage role enables the ability to carry out the most common triage activities, such as applying labels and closing/reopening/assigning issues. diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md index 29c0554d35fd7f..f7c246f4dc1cf1 100644 --- a/doc/guides/contributing/pull-requests.md +++ b/doc/guides/contributing/pull-requests.md @@ -34,7 +34,7 @@ ## Dependencies -Node.js has several bundled dependencies in the *deps/* and the *tools/* +Node.js has several bundled dependencies in the _deps/_ and the _tools/_ directories that are not part of the project proper. Changes to files in those directories should be sent to their respective projects. Do not send a patch to Node.js. We cannot accept such patches. @@ -161,19 +161,22 @@ notes about [commit squashing](#commit-squashing). A good commit message should describe what changed and why. 1. The first line should: + * contain a short description of the change (preferably 50 characters or less, and no more than 72 characters) * be entirely in lowercase with the exception of proper nouns, acronyms, and - the words that refer to code, like function/variable names + the words that refer to code, like function/variable names * be prefixed with the name of the changed [subsystem](#appendix-subsystems) - and start with an imperative verb. Check the output of `git log --oneline - files/you/changed` to find out what subsystems your changes touch. + and start with an imperative verb. Check the output of `git log --oneline + files/you/changed` to find out what subsystems your changes touch. Examples: + * `net: add localAddress and localPort to Socket` * `src: fix typos in async_wrap.h` 2. Keep the second line blank. + 3. Wrap all other lines at 72 columns (except for long URLs). 4. If your patch fixes an open issue, you can add a reference to it at the end @@ -181,13 +184,14 @@ A good commit message should describe what changed and why. references use `Refs:`. Examples: + * `Fixes: https://github.com/nodejs/node/issues/1337` * `Refs: https://eslint.org/docs/rules/space-in-parens.html` * `Refs: https://github.com/nodejs/node/pull/3615` 5. If your commit introduces a breaking change (`semver-major`), it should -contain an explanation about the reason of the breaking change, which -situation would trigger the breaking change and what is the exact change. + contain an explanation about the reason of the breaking change, which + situation would trigger the breaking change and what is the exact change. Sample complete commit message: @@ -322,7 +326,7 @@ reviews a pull request they may find specific details that they would like to see changed or fixed. These may be as simple as fixing a typo, or may involve substantive changes to the code you have written. While such requests are intended to be helpful, they may come across as abrupt or unhelpful, especially -requests to change things that do not include concrete suggestions on *how* to +requests to change things that do not include concrete suggestions on _how_ to change them. 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: 4. Is the commit message readable and correct? If it contains a breaking change is it clear enough? -When changes are necessary, *request* them, do not *demand* them, and do not +When changes are necessary, _request_ them, do not _demand_ them, and do not assume that the submitter already knows how to add a test or run a benchmark. Specific performance optimization techniques, coding styles and conventions @@ -404,7 +408,7 @@ with the appropriate reason to keep the conversation flow concise and relevant. ### Be aware of the person behind the code -Be aware that *how* you communicate requests and reviews in your feedback can +Be aware that _how_ you communicate requests and reviews in your feedback can have a significant impact on the success of the pull request. Yes, we may land a particular change that makes Node.js better, but the individual might just 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. When explicitly using the "Changes requested" component of the GitHub Approval Workflow, show empathy. That is, do not be rude or abrupt with your feedback and offer concrete suggestions for improvement, if possible. If you're not -sure *how* a particular change can be improved, say so. +sure _how_ a particular change can be improved, say so. Most importantly, after leaving such requests, it is courteous to make yourself available later to check whether your comments have been addressed. @@ -494,7 +498,7 @@ changing working functional code just for the sake of changing. If a particular pull request introduces a performance or functional regression, rather than simply rejecting the pull request, take the time to -work *with* the contributor on improving the change. Offer feedback and +work _with_ the contributor on improving the change. Offer feedback and advice on what would make the pull request acceptable, and do not assume that the contributor should already know how to do that. Be explicit in your feedback. diff --git a/doc/guides/cpp-style-guide.md b/doc/guides/cpp-style-guide.md index 10fd7f9a00a5c6..2d651049322173 100644 --- a/doc/guides/cpp-style-guide.md +++ b/doc/guides/cpp-style-guide.md @@ -14,9 +14,9 @@ Node.js codebase not related to stylistic issues. * [Align function arguments vertically](#align-function-arguments-vertically) * [Initialization lists](#initialization-lists) * [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) - * [`snake_case` for C-like structs](#snake_case-for-c-like-structs) + * [`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) + * [`snake_case` for C-like structs](#snake\_case-for-c-like-structs) * [Space after `template`](#space-after-template) * [Memory management](#memory-management) * [Memory allocation](#memory-allocation) @@ -174,7 +174,7 @@ class Foo { ### `snake_case` for C-like structs -For plain C-like structs snake_case can be used. +For plain C-like structs snake\_case can be used. ```cpp struct foo_bar { @@ -267,7 +267,8 @@ class ExampleClass { When working with typed arrays that involve direct data modification from C++, use an `AliasedBuffer` when possible. The API abstraction and -the usage scope of `AliasedBuffer` are documented in [aliased_buffer.h][]. +the usage scope of `AliasedBuffer` are documented in +[aliased\_buffer.h][aliased_buffer.h]. ```cpp // Create an AliasedBuffer. diff --git a/doc/guides/diagnostic-tooling-support-tiers.md b/doc/guides/diagnostic-tooling-support-tiers.md index 7672606c8fad99..556c87e6a95493 100644 --- a/doc/guides/diagnostic-tooling-support-tiers.md +++ b/doc/guides/diagnostic-tooling-support-tiers.md @@ -93,56 +93,56 @@ The tools are currently assigned to Tiers as follows: ## Tier 1 -| Tool Type | Tool/API Name | Regular Testing in Node.js CI | Integrated with Node.js | Target Tier | -|-----------|---------------------------|-------------------------------|-------------------------|-------------| -| FFDC | diagnostic report | Yes | Yes | 1 | -| | | | | | +| Tool Type | Tool/API Name | Regular Testing in Node.js CI | Integrated with Node.js | Target Tier | +| --------- | ----------------- | ----------------------------- | ----------------------- | ----------- | +| FFDC | diagnostic report | Yes | Yes | 1 | +| | | | | | ## Tier 2 | Tool Type | Tool/API Name | Regular Testing in Node.js CI | Integrated with Node.js | Target Tier | -|-----------|---------------|-------------------------------|-------------------------|-------------| +| --------- | ------------- | ----------------------------- | ----------------------- | ----------- | | | | | | | ## Tier 3 | Tool Type | Tool/API Name | Regular Testing in Node.js CI | Integrated with Node.js | Target Tier | -|-----------|--------------------------------------|-------------------------------|-------------------------|-------------| -| Profiling | V8 CPU profiler | Partial (V8 Tests) | Yes | 1 | -| Profiling | --prof/--prof-process flags | Yes | Yes | 1 | -| Profiling | V8 CodeEventHandler API | Partial (V8 Tests) | Yes | 2 | -| Profiling | V8 --interpreted-frames-native-stack | Yes | Yes | 2 | -| Profiling | Linux perf | Yes | Partial | 2 | +| --------- | ------------------------------------ | ----------------------------- | ----------------------- | ----------- | +| Profiling | V8 CPU profiler | Partial (V8 Tests) | Yes | 1 | +| Profiling | --prof/--prof-process flags | Yes | Yes | 1 | +| Profiling | V8 CodeEventHandler API | Partial (V8 Tests) | Yes | 2 | +| Profiling | V8 --interpreted-frames-native-stack | Yes | Yes | 2 | +| Profiling | Linux perf | Yes | Partial | 2 | ## Tier 4 | Tool Type | Tool/API Name | Regular Testing in Node.js CI | Integrated with Node.js | Target Tier | -|-----------|---------------|-------------------------------|-------------------------|-------------| +| --------- | ------------- | ----------------------------- | ----------------------- | ----------- | | | | | | | ## Not yet classified | Tool Type | Tool/API Name | Regular Testing in Node.js CI | Integrated with Node.js | Target Tier | -|-----------|---------------------------|-------------------------------|-------------------------|-------------| -| FFDC | node-report | No | No | 1 | -| Memory | mdb_V8 | No | No | 4 | -| Memory | node-heapdump | No | No | 2 | -| Memory | V8 heap profiler | No | Yes | 1 | -| Memory | V8 sampling heap profiler | No | Yes | 1 | -| AsyncFlow | Async Hooks (API) | ? | Yes | 1 | -| Debugger | V8 Debug protocol (API) | No | Yes | 1 | -| Debugger | Command line Debug Client | ? | Yes | 1 | -| Debugger | llnode | ? | No | 2 | -| Debugger | Chrome Dev tools | ? | No | 3 | +| --------- | ------------------------- | ----------------------------- | ----------------------- | ----------- | +| FFDC | node-report | No | No | 1 | +| Memory | mdb\_V8 | No | No | 4 | +| Memory | node-heapdump | No | No | 2 | +| Memory | V8 heap profiler | No | Yes | 1 | +| Memory | V8 sampling heap profiler | No | Yes | 1 | +| AsyncFlow | Async Hooks (API) | ? | Yes | 1 | +| Debugger | V8 Debug protocol (API) | No | Yes | 1 | +| Debugger | Command line Debug Client | ? | Yes | 1 | +| Debugger | llnode | ? | No | 2 | +| Debugger | Chrome Dev tools | ? | No | 3 | | Debugger | Chakracore - time-travel | No | Data source only | too early | -| Tracing | trace_events (API) | No | Yes | 1 | -| Tracing | DTrace | No | Partial | 3 | -| Tracing | LTTng | No | Removed? | N/A | -| Tracing | ETW | No | Partial | 3 | -| Tracing | Systemtap | No | Partial | ? | -| Profiling | DTrace | No | Partial | 3 | -| Profiling | Windows Xperf | No | ? | ? | -| Profiling | 0x | No | No | 4 | +| Tracing | trace\_events (API) | No | Yes | 1 | +| Tracing | DTrace | No | Partial | 3 | +| Tracing | LTTng | No | Removed? | N/A | +| Tracing | ETW | No | Partial | 3 | +| Tracing | Systemtap | No | Partial | ? | +| Profiling | DTrace | No | Partial | 3 | +| Profiling | Windows Xperf | No | ? | ? | +| Profiling | 0x | No | No | 4 | | Profiling | node-clinic | No | No | too early | -| F/P/T | appmetrics | No | No | ? | -| M/T | eBPF tracing tool | No | No | ? | +| F/P/T | appmetrics | No | No | ? | +| M/T | eBPF tracing tool | No | No | ? | diff --git a/doc/guides/doc-style-guide.md b/doc/guides/doc-style-guide.md index 26322e6c7ba3b0..60adcbf4e6b7f1 100644 --- a/doc/guides/doc-style-guide.md +++ b/doc/guides/doc-style-guide.md @@ -36,7 +36,8 @@ this guide. * When documenting APIs, update the YAML comment associated with the API as appropriate. This is especially true when introducing or deprecating an API. * For code blocks: - * Use [language][]-aware fences. (```js) + * Use [language][]-aware fences. (\`\`\`js) + * For the [info string][], use one of the following. | Meaning | Info string | @@ -69,14 +70,14 @@ this guide. * Instances should use camelCase. * Denote methods with parentheses: `socket.end()` instead of `socket.end`. * Function arguments or object properties should use the following format: - * ```* `name` {type|type2} Optional description. **Default:** `value`.``` + * ``* `name` {type|type2} Optional description. **Default:** `value`.`` - * For example: * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. + * For example: \* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. * The `type` should refer to a Node.js type or a [JavaScript type][]. * Function returns should use the following format: - * * Returns: {type|type2} Optional description. - * E.g. * Returns: {AsyncHook} A reference to `asyncHook`. + * \* Returns: {type|type2} Optional description. + * E.g. \* Returns: {AsyncHook} A reference to `asyncHook`. * Use official styling for capitalization in products and projects. * OK: JavaScript, Google's V8 @@ -85,7 +86,9 @@ this guide. * When referring to the executable, _`node`_ is acceptable. * [Be direct][]. + + * When referring to a version of Node.js in prose, use _Node.js_ and the version number. Do not prefix the version number with _v_ in prose. This is to avoid confusion about whether _v8_ refers to Node.js 8.x or the V8 JavaScript diff --git a/doc/guides/investigating_native_memory_leak.md b/doc/guides/investigating_native_memory_leak.md index f808675f5328bc..8c193d1285fe29 100644 --- a/doc/guides/investigating_native_memory_leak.md +++ b/doc/guides/investigating_native_memory_leak.md @@ -34,6 +34,7 @@ apt-get install valgrind ``` ## Invocation + The simplest invocation of valgrind is: ```console @@ -186,7 +187,7 @@ definitely lost and the question is how to find where that memory was allocated. The next step is to rerun as suggested in the output with `--leak-check=full`: -``` bash +```bash user1@minikube1:~/valgrind/node-addon-examples/1_hello_world/napi$ valgrind --leak-check=full node hello.js ==4174== Memcheck, a memory error detector ==4174== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al. @@ -412,19 +413,23 @@ To get additional information with valgrind: * Check out the Node.js source corresponding to the release that you want to debug. For example: + ```console git clone https://github.com/nodejs/node.git git checkout v12.14.1 ``` + * Compile with debug enabled (for additional info see -[building a debug build](https://github.com/nodejs/node/blob/v12.14.1/BUILDING.md#building-a-debug-build)). -For example, on *nix: + [building a debug build](https://github.com/nodejs/node/blob/v12.14.1/BUILDING.md#building-a-debug-build)). + For example, on \*nix: + ```console ./configure --debug make -j4 ``` + * Make sure to run with your compiled debug version of Node.js. Having used - `./configure --debug`, two binaries will have been built when `make` was run. + `./configure --debug`, two binaries will have been built when `make` was run. You must use the one which is in `out/Debug`. Running valgrind using the debug build of Node.js shows: @@ -444,4 +449,4 @@ Running valgrind using the debug build of Node.js shows: ``` Now we can see the specific file name and line in the Node.js code which -caused the allocation (inspector_agent.cc:140). +caused the allocation (inspector\_agent.cc:140). diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 6234b29bc2b225..8b79d3b3ca8921 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -37,13 +37,13 @@ documented [on the V8 wiki][V8MergingPatching]. The summary of the process is: * V8 only supports active branches. There is no testing done on any branches older than the current stable/beta/master. -* A fix needing backport is tagged w/ *merge-request-x.x* tag. This can be done +* A fix needing backport is tagged w/ _merge-request-x.x_ tag. This can be done by anyone interested in getting the fix backported. Issues with this tag are reviewed by the V8 team regularly as candidates for backporting. * Fixes need some 'baking time' before they can be approved for backporting. This means waiting a few days to ensure that no issues are detected on the canary/beta builds. -* Once ready, the issue is tagged w/ *merge-approved-x.x* and one can do the +* Once ready, the issue is tagged w/ _merge-approved-x.x_ and one can do the actual merge by using the scripts on the [wiki page][V8MergingPatching]. * Merge requests to an abandoned branch will be rejected. * Only bug fixes are accepted for backporting. @@ -190,7 +190,7 @@ backport the fix: bug using this [Node.js specific template][V8TemplateMergeRequest]. * If a bug already exists * Add a reference to the GitHub issue. - * Attach *merge-request-x.x* labels to the bug for any active branches + * Attach _merge-request-x.x_ labels to the bug for any active branches that still contain the bug. * Once the merge has been approved, it should be merged using the [merge script documented in the V8 wiki][V8MergingPatching]. Merging requires @@ -210,15 +210,15 @@ to be cherry-picked in the Node.js repository and V8-CI must test the change. * For each abandoned V8 branch corresponding to an LTS branch that is affected by the bug: - * Checkout a branch off the appropriate *vY.x-staging* branch (e.g. - *v6.x-staging* to fix an issue in V8 5.1). + * Checkout a branch off the appropriate _vY.x-staging_ branch (e.g. + _v6.x-staging_ to fix an issue in V8 5.1). * Cherry-pick the commit(s) from the V8 repository. * Increase the `v8_embedder_string` number in `common.gypi`. * In some cases the patch may require extra effort to merge in case V8 has changed substantially. For important issues, we may be able to lean on the V8 team to get help with reimplementing the patch. * Open a cherry-pick pull request on `nodejs/node` targeting the - *vY.x-staging* branch and notify the `@nodejs/v8` team. + _vY.x-staging_ branch and notify the `@nodejs/v8` team. * Run the Node.js [V8 CI][] in addition to the [Node.js CI][]. The CI uses the `test-v8` target in the `Makefile`, which uses `tools/make-v8.sh` to reconstruct a git tree in the `deps/v8` directory to @@ -233,13 +233,17 @@ From the bug we can see that it was merged by V8 into 5.2 and 5.3, and not into V8 5.1 (since it was already abandoned). Since Node.js `v6.x` uses V8 5.1, the fix needed to be cherry-picked. To cherry-pick, here's an example workflow: -* Download and apply the commit linked-to in the issue (in this case a51f429). - `curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 - --directory=deps/v8`. If the branches have diverged significantly, this may - not apply cleanly. It may help to try to cherry-pick the merge to the oldest - branch that was done upstream in V8. In this example, this would be the patch - from the merge to 5.2. The hope is that this would be closer to the V8 5.1, - and has a better chance of applying cleanly. +* Download and apply the commit linked-to in the issue (in this case a51f429): + + ```console + curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 --directory=deps/v8 + ``` + + If the branches have diverged significantly, this may not apply cleanly. It + may help to try to cherry-pick the merge to the oldest branch that was done + upstream in V8. In this example, this would be the patch from the merge to + 5.2. The hope is that this would be closer to the V8 5.1, and has a better + chance of applying cleanly. * Modify the commit message to match the format we use for V8 backports and replace yourself as the author. `git commit --amend --reset-author`. You may want to add extra description if necessary to indicate the impact of the fix @@ -333,8 +337,8 @@ curl -L https://github.com/v8/v8/compare/${V8_OLD_VERSION}...${V8_NEW_VERSION}.p # You may want to amend the commit message to describe the nature of the update ``` -V8 also keeps tags of the form *5.4-lkgr* which point to the *Last Known Good -Revision* from the 5.4 branch that can be useful in the update process above. +V8 also keeps tags of the form _5.4-lkgr_ which point to the _Last Known Good +Revision_ from the 5.4 branch that can be useful in the update process above. The [`git-node`][] tool can be used to simplify this task. Run `git node v8 minor` to apply a minor update. @@ -349,12 +353,12 @@ above. A better strategy is to 1. Audit the current master branch and look at the patches that have been floated since the last major V8 update. -1. Replace the copy of V8 in Node.js with a fresh checkout of the latest stable +2. Replace the copy of V8 in Node.js with a fresh checkout of the latest stable V8 branch. Special care must be taken to recursively update the DEPS that V8 has a compile time dependency on (at the moment of this writing, these are - only trace_event and gtest_prod.h) -1. Reset the `v8_embedder_string` variable to "-node.0" in `common.gypi`. -1. Refloat (cherry-pick) all the patches from list computed in 1) as necessary. + only trace\_event and gtest\_prod.h) +3. Reset the `v8_embedder_string` variable to "-node.0" in `common.gypi`. +4. Refloat (cherry-pick) all the patches from list computed in 1) as necessary. Some of the patches may no longer be necessary. To audit for floating patches: @@ -401,6 +405,7 @@ This would require some tooling to: * Enabled the V8-CI build in Jenkins to build from the `nodejs/v8` fork. + ### Notes 1Node.js 0.12 and older are intentionally omitted from this document diff --git a/doc/guides/maintaining-icu.md b/doc/guides/maintaining-icu.md index a9d075d47007b6..56e5c58aa0f521 100644 --- a/doc/guides/maintaining-icu.md +++ b/doc/guides/maintaining-icu.md @@ -96,7 +96,7 @@ Node.js is built. ## How to upgrade ICU * Make sure your Node.js workspace is clean (`git status` -should be sufficient). + should be sufficient). * Configure Node.js with the specific [ICU version](http://site.icu-project.org/download) you want to upgrade to, for example: @@ -113,7 +113,7 @@ make * If there are ICU version-specific changes needed, you may need to make changes in `tools/icu/icu-generic.gyp` or add patch files to `tools/icu/patches`. * Specifically, look for the lists in `sources!` in the `tools/icu/icu-generic.gyp` for - files to exclude. + files to exclude. * Verify the Node.js build works: @@ -174,8 +174,8 @@ tools/license-builder.sh ``` * Update the URL and hash for the full ICU file in `tools/icu/current_ver.dep`. -It should match the ICU URL used in the first step. When this is done, the -following should build with small ICU. + It should match the ICU URL used in the first step. When this is done, the + following should build with small ICU. ```bash # clean up @@ -187,11 +187,11 @@ make test-ci * commit the change to `tools/icu/current_ver.dep` and `LICENSE` files. - * Note: To simplify review, I often will “pre-land” this patch, meaning that - I run the patch through `curl -L https://github.com/nodejs/node/pull/xxx.patch - | git am -3 --whitespace=fix` per the collaborator’s guide… and then push that - patched branch into my PR's branch. This reduces the whitespace changes that - show up in the PR, since the final land will eliminate those anyway. + * To simplify review, I often will “pre-land” this patch, meaning that I run + `curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix` + per the collaborator’s guide… and then push that patched branch into my + PR's branch. This reduces the whitespace changes that show up in the PR, + since the final land will eliminate those anyway. ## Floating patches to ICU @@ -248,17 +248,17 @@ patch to ICU is required. Though it seems expedient to simply change a file in `deps/icu-small`, this is not the right approach for the following reasons: 1. **Repeatability.** Given the complexity of merging in a new ICU version, -following the steps above in the prior section of this document ought to be -repeatable without concern for overriding a patch. + following the steps above in the prior section of this document ought to be + repeatable without concern for overriding a patch. 2. **Verifiability.** Given the number of files modified in an ICU PR, -a floating patch could easily be missed or dropped altogether next time -something is landed. + a floating patch could easily be missed or dropped altogether next time + something is landed. 3. **Compatibility.** There are a number of ways that ICU can be loaded into -Node.js (see the top level README.md). Only modifying `icu-small` would cause -the patch not to be landed in case the user specifies the ICU source code -another way. + Node.js (see the top level README.md). Only modifying `icu-small` would cause + the patch not to be landed in case the user specifies the ICU source code + another way. [CLDR]: http://cldr.unicode.org/ [Ecma402]: https://github.com/tc39/ecma402 diff --git a/doc/guides/maintaining-openssl.md b/doc/guides/maintaining-openssl.md index 0ed5b35ed57b89..7e999f87f892b0 100644 --- a/doc/guides/maintaining-openssl.md +++ b/doc/guides/maintaining-openssl.md @@ -28,6 +28,7 @@ Branches are used per OpenSSL version (for instance, . ## Requirements + * Linux environment. * `perl` Only Perl version 5 is tested. * `nasm` () Version 2.11 or higher is needed. @@ -71,6 +72,7 @@ release). The commit message can be written as (with the openssl version set to the relevant value): + ```text deps: upgrade openssl sources to OpenSSL_1_1_1j @@ -90,6 +92,7 @@ This updates all sources in deps/openssl/openssl by: Use `make` to regenerate all platform dependent files in `deps/openssl/config/archs/`: + ```console # On non-Linux machines % make gen-openssl @@ -103,13 +106,14 @@ Use `make` to regenerate all platform dependent files in Check diffs to ensure updates are right. Even if there are no updates in openssl sources, `buildinf.h` files will be updated because they have timestamp data in them. + ```console % git diff -- deps/openssl ``` -*Note*: On Windows, OpenSSL Configure generates a `makefile` that can be +_Note_: On Windows, OpenSSL Configure generates a `makefile` that can be used for the `nmake` command. The `make` command in step 2 (above) uses - `Makefile_VC-WIN64A` and `Makefile_VC-WIN32` that are manually +`Makefile_VC-WIN64A` and `Makefile_VC-WIN32` that are manually created. When source files or build options are updated in Windows, it needs to change these two Makefiles by hand. If you are not sure, please ask @shigeki for details. @@ -118,6 +122,7 @@ please ask @shigeki for details. Update all architecture dependent files. Do not forget to git add or remove files if they are changed before committing: + ```console % git add deps/openssl/config/archs % git add deps/openssl/openssl/include/crypto/bn_conf.h @@ -128,6 +133,7 @@ files if they are changed before committing: The commit message can be written as (with the openssl version set to the relevant value): + ```text deps: update archs files for OpenSSL-1.1.1 diff --git a/doc/guides/maintaining-root-certs.md b/doc/guides/maintaining-root-certs.md index 8ab3764aac53bf..d7fb05a4f2485a 100644 --- a/doc/guides/maintaining-root-certs.md +++ b/doc/guides/maintaining-root-certs.md @@ -20,106 +20,106 @@ the nodejs/node repository. 1. Find NSS metadata for update. - The latest released NSS version, release date, Firefox version, and Firefox - release date can be found in the [NSS release schedule][]. + The latest released NSS version, release date, Firefox version, and Firefox + release date can be found in the [NSS release schedule][]. - The tag to fetch `certdata.txt` from is found by looking for the release - version in the [tag list][]. + The tag to fetch `certdata.txt` from is found by looking for the release + version in the [tag list][]. 2. Update `certdata.txt` from the NSS release tag. - Update the tag in the commands below, and run: + Update the tag in the commands below, and run: - ```bash - cd tools/ - ./mk-ca-bundle.pl -v 2>_before - curl -O https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt - ``` + ```bash + cd tools/ + ./mk-ca-bundle.pl -v 2>_before + curl -O https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt + ``` - The `_before` file will be used later. Verify that running `mk-ca-bundle` - made no changes to `src/node_root_certs.h`. If it did, something went wrong - with the previous update. Seek help! + The `_before` file will be used later. Verify that running `mk-ca-bundle` + made no changes to `src/node_root_certs.h`. If it did, something went wrong + with the previous update. Seek help! - Update metadata in the message below, and commit `certdata.txt`: + Update metadata in the message below, and commit `certdata.txt`: - ```text - tools: update certdata.txt + ```text + tools: update certdata.txt - This is the certdata.txt[0] from NSS 3.41, released on 2018-12-03. + This is the certdata.txt[0] from NSS 3.41, released on 2018-12-03. - This is the version of NSS that will ship in Firefox 65 on - 2018-12-11. + This is the version of NSS that will ship in Firefox 65 on + 2018-12-11. - [0] https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt - ``` + [0] https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt + ``` 3. Update `node_root_certs.h` from `certdata.txt`. - Run the command below: - - ```bash - ./mk-ca-bundle.pl -v 2>_after - ``` - - Confirm that `../src/node_root_certs.h` was updated. - - Determine what changes were made by diffing the before and after files: - - ```console - % diff _before _after - 11d10 - < Parsing: Visa eCommerce Root - 106d104 - < Parsing: TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 - 113,117d110 - < Parsing: Certplus Root CA G1 - < Parsing: Certplus Root CA G2 - < Parsing: OpenTrust Root CA G1 - < Parsing: OpenTrust Root CA G2 - < Parsing: OpenTrust Root CA G3 - 134c127,136 - < Done (133 CA certs processed, 20 skipped). - --- - > Parsing: GlobalSign Root CA - R6 - > Parsing: OISTE WISeKey Global Root GC CA - > Parsing: GTS Root R1 - > Parsing: GTS Root R2 - > Parsing: GTS Root R3 - > Parsing: GTS Root R4 - > Parsing: UCA Global G2 Root - > Parsing: UCA Extended Validation Root - > Parsing: Certigna Root CA - > Done (135 CA certs processed, 16 skipped). - ``` - - Use the diff to update the message below, and commit `src/node_root_certs.h`: - - ```text - crypto: update root certificates - - Update the list of root certificates in src/node_root_certs.h with - tools/mk-ca-bundle.pl. - - Certificates added: - - GlobalSign Root CA - R6 - - OISTE WISeKey Global Root GC CA - - GTS Root R1 - - GTS Root R2 - - GTS Root R3 - - GTS Root R4 - - UCA Global G2 Root - - UCA Extended Validation Root - - Certigna Root CA - - Certificates removed: - - Visa eCommerce Root - - TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 - - Certplus Root CA G1 - - Certplus Root CA G2 - - OpenTrust Root CA G1 - - OpenTrust Root CA G2 - - OpenTrust Root CA G3 - ``` + Run the command below: + + ```bash + ./mk-ca-bundle.pl -v 2>_after + ``` + + Confirm that `../src/node_root_certs.h` was updated. + + Determine what changes were made by diffing the before and after files: + + ```console + % diff _before _after + 11d10 + < Parsing: Visa eCommerce Root + 106d104 + < Parsing: TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 + 113,117d110 + < Parsing: Certplus Root CA G1 + < Parsing: Certplus Root CA G2 + < Parsing: OpenTrust Root CA G1 + < Parsing: OpenTrust Root CA G2 + < Parsing: OpenTrust Root CA G3 + 134c127,136 + < Done (133 CA certs processed, 20 skipped). + --- + > Parsing: GlobalSign Root CA - R6 + > Parsing: OISTE WISeKey Global Root GC CA + > Parsing: GTS Root R1 + > Parsing: GTS Root R2 + > Parsing: GTS Root R3 + > Parsing: GTS Root R4 + > Parsing: UCA Global G2 Root + > Parsing: UCA Extended Validation Root + > Parsing: Certigna Root CA + > Done (135 CA certs processed, 16 skipped). + ``` + + Use the diff to update the message below, and commit `src/node_root_certs.h`: + + ```text + crypto: update root certificates + + Update the list of root certificates in src/node_root_certs.h with + tools/mk-ca-bundle.pl. + + Certificates added: + - GlobalSign Root CA - R6 + - OISTE WISeKey Global Root GC CA + - GTS Root R1 + - GTS Root R2 + - GTS Root R3 + - GTS Root R4 + - UCA Global G2 Root + - UCA Extended Validation Root + - Certigna Root CA + + Certificates removed: + - Visa eCommerce Root + - TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 + - Certplus Root CA G1 + - Certplus Root CA G2 + - OpenTrust Root CA G1 + - OpenTrust Root CA G2 + - OpenTrust Root CA G3 + ``` [NSS release schedule]: https://wiki.mozilla.org/NSS:Release_Versions [tag list]: https://hg.mozilla.org/projects/nss/tags diff --git a/doc/guides/maintaining-zlib.md b/doc/guides/maintaining-zlib.md index cdf5e2c17d6d95..4dba29bacf9127 100644 --- a/doc/guides/maintaining-zlib.md +++ b/doc/guides/maintaining-zlib.md @@ -6,6 +6,7 @@ performance improvements not currently available in standard zlib. ## Updating zlib Update zlib: + ```bash git clone https://chromium.googlesource.com/chromium/src/third_party/zlib cp deps/zlib/zlib.gyp deps/zlib/win32/zlib.def deps @@ -27,6 +28,7 @@ occurred upstream. Add zlib: `git add --all deps/zlib` Commit the changes with a message like + ```text deps: update zlib to upstream d7f3ca9 diff --git a/doc/guides/node-postmortem-support.md b/doc/guides/node-postmortem-support.md index b709c03b53d751..a0b27c65792464 100644 --- a/doc/guides/node-postmortem-support.md +++ b/doc/guides/node-postmortem-support.md @@ -67,6 +67,6 @@ sure all Node.js postmortem metadata are calculated correctly. ## Tools and references * [llnode](https://github.com/nodejs/llnode): LLDB plugin -* [`mdb_v8`](https://github.com/joyent/mdb_v8): mdb plugin +* [`mdb_v8`](https://github.com/joyent/mdb\_v8): mdb plugin * [nodejs/post-mortem](https://github.com/nodejs/post-mortem): Node.js -post-mortem working group + post-mortem working group diff --git a/doc/guides/releases.md b/doc/guides/releases.md index d3c0712b73768c..11c9a826fee237 100644 --- a/doc/guides/releases.md +++ b/doc/guides/releases.md @@ -9,13 +9,13 @@ official release builds for Node.js, hosted on . * [Who can make a release?](#who-can-make-a-release) * [1. Jenkins release access](#1-jenkins-release-access) - * [2. access](#2-nodejsorg-access) + * [2. \ access](#2-nodejsorg-access) * [3. A publicly listed GPG key](#3-a-publicly-listed-gpg-key) * [How to create a release](#how-to-create-a-release) * [0. Pre-release steps](#0-pre-release-steps) * [1. Update the staging branch](#1-update-the-staging-branch) * [2. Create a new branch for the release](#2-create-a-new-branch-for-the-release) - * [3. Update `src/node_version.h`](#3-update-srcnode_versionh) + * [3. Update `src/node_version.h`](#3-update-srcnode\_versionh) * [4. Update the changelog](#4-update-the-changelog) * [5. Create release commit](#5-create-release-commit) * [6. Propose release on GitHub](#6-propose-release-on-github) @@ -48,11 +48,11 @@ There are three relevant Jenkins jobs that should be used for a release flow: **a.** **Test runs:** **[node-test-pull-request](https://ci.nodejs.org/job/node-test-pull-request/)** -is used for a final full-test run to ensure that the current *HEAD* is stable. +is used for a final full-test run to ensure that the current _HEAD_ is stable. **b.** **Nightly builds:** (optional) **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** can be used -to create a nightly release for the current *HEAD* if public test releases are +to create a nightly release for the current _HEAD_ if public test releases are required. Builds triggered with this job are published straight to and are available for public download. @@ -64,7 +64,7 @@ a manual step once they are ready (see below). The [Node.js build team](https://github.com/nodejs/build) is able to provide this access to individuals authorized by the TSC. -### 2. access +### 2. \ access The _dist_ user on nodejs.org controls the assets available in . is an alias for @@ -158,7 +158,7 @@ For each PR: * Check approvals (you can approve yourself). * Check that the commit metadata was not changed from the `master` commit. * If there are merge conflicts, ask the PR author to rebase. -Simple conflicts can be resolved when landing. + Simple conflicts can be resolved when landing. When landing the PR add the `Backport-PR-URL:` line to each commit. Close the backport PR with `Landed in ...`. Update the label on the original PR from @@ -185,10 +185,10 @@ Carefully review the list of commits: * Checking for errors (incorrect `PR-URL`) * Checking semver status - Commits labeled as `semver-minor` or `semver-major` -should only be cherry-picked when appropriate for the type of release being -made. + should only be cherry-picked when appropriate for the type of release being + made. * If you think it's risky and the change should wait for a while, add the -`baking-for-lts` tag. + `baking-for-lts` tag. When you are ready to cherry-pick commits, you can automate with the following command. (For semver-minor releases, make sure to remove the `semver-minor` tag @@ -202,7 +202,7 @@ When cherry-picking commits, if there are simple conflicts you can resolve them. Otherwise, add the `backport-requested-vN.x` label to the original PR and post a comment stating that it does not land cleanly and will require a backport PR. You can refer the owner of the PR to the "[Backporting to Release - Lines](https://github.com/nodejs/node/blob/HEAD/doc/guides/backporting-to-release-lines.md)" guide. +Lines](https://github.com/nodejs/node/blob/HEAD/doc/guides/backporting-to-release-lines.md)" guide. If commits were cherry-picked in this step, check that the test still pass. @@ -264,7 +264,7 @@ $ changelog-maker --group --filter-release --start-ref v1.2.2 `--filter-release` will remove the release commit from the previous release. -#### Step 2: Update the appropriate doc/changelogs/CHANGELOG_*.md file +#### Step 2: Update the appropriate doc/changelogs/CHANGELOG\_\*.md file There is a separate `CHANGELOG_Vx.md` file for each major Node.js release line. These are located in the `doc/changelogs/` directory. Once the formatted list of @@ -272,7 +272,7 @@ changes is collected, it must be added to the top of the relevant changelog file in the release branch (e.g. a release for Node.js v4 would be added to the `/doc/changelogs/CHANGELOG_V4.md`). -**Please do *not* add the changelog entries to the root `CHANGELOG.md` file.** +**Please do _not_ add the changelog entries to the root `CHANGELOG.md` file.** The new entry should take the following form: @@ -307,7 +307,7 @@ all. At the top of the root `CHANGELOG.md` file, there is a table indexing all releases in each major release line. A link to the new release needs to be added -to it. Follow the existing examples and be sure to add the release to the *top* +to it. Follow the existing examples and be sure to add the release to the _top_ of the list. The most recent release for each release line is shown in **bold** in the index. When updating the index, please make sure to update the display accordingly by removing the bold styling from the previous release. @@ -318,10 +318,13 @@ If this release includes new APIs then it is necessary to document that they were first added in this version. The relevant commits should already include `REPLACEME` tags as per the example in the [docs README](../../tools/doc/README.md). Check for these tags with + ```console grep REPLACEME doc/api/*.md ``` + and substitute this node version with + ```console sed -i "s/REPLACEME/$VERSION/g" doc/api/*.md` or `perl -pi -e "s/REPLACEME/$VERSION/g" doc/api/*.md ``` @@ -459,13 +462,18 @@ the build before moving forward. Once you have produced builds that you're happy with, create a new tag. By waiting until this stage to create tags, you can discard a proposed release if something goes wrong or additional commits are required. Once you have created a -tag and pushed it to GitHub, you ***must not*** delete and re-tag. If you make +tag and pushed it to GitHub, you _**must not**_ delete and re-tag. If you make a mistake after tagging then you'll have to version-bump and start again and count that tag/version as lost. -Tag summaries have a predictable format, look at a recent tag to see, `git tag --v v6.0.0`. The message should look something like `2016-04-26 Node.js v6.0.0 -(Current) Release`. +Tag summaries have a predictable format. Look at a recent tag to see: + +```console +git tag -v v6.0.0 +``` + +The message should look something like +`2016-04-26 Node.js v6.0.0 (Current) Release`. Install `git-secure-tag` npm module: @@ -480,7 +488,7 @@ $ git secure-tag -sm "YYYY-MM-DD Node.js vx.y.z ( ``` -*Note*: Please do not push the tag unless you are ready to complete the +_Note_: Please do not push the tag unless you are ready to complete the remainder of the release steps. ### 15. Promote and sign the release builds @@ -616,8 +624,7 @@ however. **d.** Use `scp` to download `SHASUMS256.txt` to a temporary directory on your computer. -**e.** Sign the `SHASUMS256.txt` file using a command similar to: `gpg ---default-key YOURKEY --digest-algo SHA256 --clearsign /path/to/SHASUMS256.txt`. +**e.** Sign the `SHASUMS256.txt` file using a command similar to: `gpg --default-key YOURKEY --digest-algo SHA256 --clearsign /path/to/SHASUMS256.txt`. You will be prompted by GPG for your password. The signed file will be named SHASUMS256.txt.asc. @@ -628,6 +635,7 @@ SHASUMS256.txt.sig. **g.** Upload the `SHASUMS256.txt` files back to the server into the release directory. + **It is possible to only sign a release by running `./tools/release.sh -s @@ -655,13 +663,16 @@ This script will use the promoted builds and changelog to generate the post. Run * You can add a short blurb just under the main heading if you want to say something important, otherwise the text should be publication ready. + * The links to the download files won't be complete unless you waited for the ARMv6 builds. Any downloads that are missing will have `*Coming soon*` next to them. It's your responsibility to manually update these later when you have the outstanding builds. + * The `SHASUMS256.txt.asc` content is at the bottom of the post. When you update the list of tarballs you'll need to copy/paste the new contents of this file to reflect those changes. + * Always use pull-requests on the [nodejs.org repository][]. Be respectful of the website team, but you do not have to wait for PR sign-off. Please use the following commit message format: @@ -691,7 +702,7 @@ Close your release proposal PR and delete the proposal branch. The nodejs.org website will automatically rebuild and include the new version. To announce the build on Twitter through the official @nodejs account, email -[pr@nodejs.org](mailto:pr@nodejs.org) with a message such as: + with a message such as: > v5.8.0 of @nodejs is out: > … @@ -719,7 +730,7 @@ To mark a release line as LTS, the following changes must be made to * The `NODE_PATCH_VERSION` macro must be set to `0` * The `NODE_VERSION_IS_LTS` macro must be set to `1` * The `NODE_VERSION_LTS_CODENAME` macro must be set to the code name selected -for the LTS release. + for the LTS release. For example: diff --git a/doc/guides/security-release-process.md b/doc/guides/security-release-process.md index a03e20b9c9278e..98f3830d9119b8 100644 --- a/doc/guides/security-release-process.md +++ b/doc/guides/security-release-process.md @@ -2,8 +2,8 @@ The security release process covers the steps required to plan/implement a security release. This document is copied into the description of the Next -Security Release and used to track progress on the release. It contains ***TEXT -LIKE THIS*** which will be replaced during the release process with the +Security Release and used to track progress on the release. It contains _**TEXT +LIKE THIS**_ which will be replaced during the release process with the information described. ## Planning @@ -12,25 +12,25 @@ information described. `Next Security Release`, and put this checklist in the description. * [ ] Get agreement on the list of vulnerabilities to be addressed: - * ***H1 REPORT LINK***: ***DESCRIPTION*** (***CVE or H1 CVE request link***) - * v10.x, v12.x: ***LINK to PR URL*** + * _**H1 REPORT LINK**_: _**DESCRIPTION**_ (_**CVE or H1 CVE request link**_) + * v10.x, v12.x: _**LINK to PR URL**_ * ... * [ ] PR release announcements in [private](https://github.com/nodejs-private/nodejs.org-private): * (Use previous PRs as templates. Don't forget to update the site banner and the date in the slug so that it will move to the top of the blog list.) - * [ ] pre-release: ***LINK TO PR*** - * [ ] post-release: ***LINK TO PR*** + * [ ] pre-release: _**LINK TO PR**_ + * [ ] post-release: _**LINK TO PR**_ * Ask the HackerOne reporter if they would like to be credited on the security release blog page: ```text Thank you to for reporting this vulnerability. ``` -* [ ] Get agreement on the planned date for the release: ***RELEASE DATE*** +* [ ] Get agreement on the planned date for the release: _**RELEASE DATE**_ * [ ] Get release team volunteers for all affected lines: - * v12.x: ***NAME of RELEASER(S)*** + * v12.x: _**NAME of RELEASER(S)**_ * ... other lines, if multiple releasers ## Announcement (one week in advance of the planned release) @@ -42,14 +42,14 @@ information described. * Approved * Pass `make test` * Have CVEs - * Make sure that dependent libraries have CVEs for their issues. We should - only create CVEs for vulnerabilities in Node.js itself. This is to avoid - having duplicate CVEs for the same vulnerability. + * Make sure that dependent libraries have CVEs for their issues. We should + only create CVEs for vulnerabilities in Node.js itself. This is to avoid + having duplicate CVEs for the same vulnerability. * Described in the pre/post announcements -* [ ] Pre-release announcement [email][]: ***LINK TO EMAIL*** - * Subject: `Node.js security updates for all active release lines, Month Year` - * Body: +* [ ] Pre-release announcement [email][]: _**LINK TO EMAIL**_ + * Subject: `Node.js security updates for all active release lines, Month Year` + * Body: ```text The Node.js project will release new versions of all supported release lines on or shortly after Day of week, Month Day of Month, Year For more information see: https://nodejs.org/en/blog/vulnerability/month-year-security-releases/ @@ -62,7 +62,7 @@ The google groups UI does not support adding a CC, until we figure out a better way, forward the email you receive to `oss-security@lists.openwall.com` as a CC. -* [ ] Pre-release announcement to nodejs.org blog: ***LINK TO BLOG*** +* [ ] Pre-release announcement to nodejs.org blog: _**LINK TO BLOG**_ (Re-PR the pre-approved branch from nodejs-private/nodejs.org-private to nodejs/nodejs.org) @@ -78,9 +78,10 @@ out a better way, forward the email you receive to https://nodejs.org/en/blog/vulnerability/month-year-security-releases/ ``` + * [ ] Request releaser(s) to start integrating the PRs to be released. -* [ ] Notify [docker-node][] of upcoming security release date: ***LINK*** +* [ ] Notify [docker-node][] of upcoming security release date: _**LINK**_ ```text Heads up of Node.js security releases Day Month Year @@ -103,16 +104,16 @@ out a better way, forward the email you receive to * [ ] [Unlock CI](https://github.com/nodejs/build/blob/HEAD/doc/jenkins-guide.md#after-the-release) -* [ ] Post-release announcement in reply [email][]: ***LINK TO EMAIL*** - * CC: `oss-security@lists.openwall.com` - * Subject: `Node.js security updates for all active release lines, Month Year` - * Body: +* [ ] Post-release announcement in reply [email][]: _**LINK TO EMAIL**_ + * CC: `oss-security@lists.openwall.com` + * Subject: `Node.js security updates for all active release lines, Month Year` + * Body: ```text The Node.js project has now released new versions of all supported release lines. For more information see: https://nodejs.org/en/blog/vulnerability/month-year-security-releases/ ``` -* [ ] Post-release announcement to Nodejs.org blog: ***LINK TO BLOG POST*** +* [ ] Post-release announcement to Nodejs.org blog: _**LINK TO BLOG POST**_ * (Re-PR the pre-approved branch from nodejs-private/nodejs.org-private to nodejs/nodejs.org) @@ -124,6 +125,7 @@ out a better way, forward the email you receive to https://nodejs.org/en/blog/vulnerability/month-year-security-releases/ ``` + * [ ] Comment in [docker-node][] issue that release is ready for integration. The docker-node team will build and release docker image updates. @@ -136,7 +138,7 @@ out a better way, forward the email you receive to * [ ] PR machine-readable JSON descriptions of the vulnerabilities to the [core](https://github.com/nodejs/security-wg/tree/HEAD/vuln/core) - vulnerability DB. ***LINK TO PR*** + vulnerability DB. _**LINK TO PR**_ * For each vulnerability add a `#.json` file, one can copy an existing [json](https://github.com/nodejs/security-wg/blob/0d82062d917cb9ddab88f910559469b2b13812bf/vuln/core/78.json) file, and increment the latest created file number and use that as the name diff --git a/doc/guides/strategic-initiatives.md b/doc/guides/strategic-initiatives.md index 3a0c2c12c7c8a8..2bb7b0d4c51878 100644 --- a/doc/guides/strategic-initiatives.md +++ b/doc/guides/strategic-initiatives.md @@ -6,32 +6,32 @@ agenda to ensure they are active and have the support they need. ## Current initiatives -| Initiative | Champion | Links | -|---------------------------|-----------------------------|------------------------------------------------------------------------------------------| -| Core Promise APIs | [Antoine du Hamel][aduh95] | | +| Initiative | Champion | Links | +| ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------- | +| Core Promise APIs | [Antoine du Hamel][aduh95] | | | Future of Build Toolchain | [Mary Marchini][mmarchini] | , | -| QUIC / HTTP3 | [James M Snell][jasnell] | | +| QUIC / HTTP3 | [James M Snell][jasnell] | | | Startup performance | [Joyee Cheung][joyeecheung] | | -| V8 Currency | [Michaël Zasso][targos] | | +| V8 Currency | [Michaël Zasso][targos] | |
List of completed initiatives ## Completed initiatives -| Initiative | Champion | Links | -|--------------------|----------------------------|--------------------------------------------------| +| Initiative | Champion | Links | +| ------------------ | -------------------------- | -------------------------------------------------------------------- | | Build resources | Michael Dawson | | -| CVE Management | Michael Dawson | | -| Governance | Myles Borins | | -| Moderation Team | Rich Trott | | -| Modules | Myles Borins | | -| N-API | Michael Dawson | | -| npm Integration | Myles Borins | | -| OpenSSL Evolution | Rod Vagg | | -| Open Web Standards | Myles Borins, Joyee Cheung | | -| VM module fix | Franziska Hinkelmann | | -| Workers | Anna Henningsen | | +| CVE Management | Michael Dawson | | +| Governance | Myles Borins | | +| Moderation Team | Rich Trott | | +| Modules | Myles Borins | | +| N-API | Michael Dawson | | +| npm Integration | Myles Borins | | +| OpenSSL Evolution | Rod Vagg | | +| Open Web Standards | Myles Borins, Joyee Cheung | | +| VM module fix | Franziska Hinkelmann | | +| Workers | Anna Henningsen | |
diff --git a/doc/guides/technical-values.md b/doc/guides/technical-values.md index d248696ba51e01..f6d41207d16916 100644 --- a/doc/guides/technical-values.md +++ b/doc/guides/technical-values.md @@ -24,8 +24,10 @@ and so on. ## Value descriptions ### 1 - Developer experience + We value ensuring that developers are productive and enjoy developing with Node.js. Some key elements of this include: + * Approachability (both technical and community) * Great documentation * Bundling friction-reducing APIs and components, even though @@ -36,9 +38,11 @@ with Node.js. Some key elements of this include: * Enabling/supporting external packages to ensure overall developer experience ### 2 - Stability + Whenever possible, we seek to ensure that working code continues to work. To keep the trust of developers and users, we value stability. Some key elements of this include: + * Backward compatibility * Stable releases on a predictable schedule * A strong safety net, including testing how changes @@ -46,9 +50,11 @@ Some key elements of this include: * Careful consideration of what goes into Long Term Support (LTS) releases ### 3 - Operational qualities + We value keeping Node.js safe, performant, and lightweight. We value enabling the ability to investigate and debug problems in development and production. Some key elements of this include: + * High throughput (speed) * Fast startup * Small binary size @@ -58,17 +64,21 @@ development and production. Some key elements of this include: * Responsible security practices ### 4 - Node.js maintainer experience + We value the productivity and happiness of the Node.js maintainers. Some key elements of this include: + * Approachability of the codebase * Good internal documentation and guides * Low-friction policies and processes * Good CI and tooling to make maintainers productive ### 5 - Up to date technology and APIs + We value providing developers with modern APIs and technologies following existing standards whenever possible. Some key elements of this include: + * Participating in standards work and organizations * Web API compatibility * Supporting and exposing new technologies and standards through early adoption diff --git a/doc/guides/using-internal-errors.md b/doc/guides/using-internal-errors.md index fe7bafb7be6827..b55b187bff0152 100644 --- a/doc/guides/using-internal-errors.md +++ b/doc/guides/using-internal-errors.md @@ -66,6 +66,7 @@ classes by providing additional arguments. The other ones will be exposed as properties of the main class: + ```js E('EXAMPLE_KEY', 'Error message', TypeError, RangeError); diff --git a/doc/guides/writing-and-running-benchmarks.md b/doc/guides/writing-and-running-benchmarks.md index 59f7e6c63b65ce..bc54e7123c27ca 100644 --- a/doc/guides/writing-and-running-benchmarks.md +++ b/doc/guides/writing-and-running-benchmarks.md @@ -279,9 +279,9 @@ The `compare.js` tool will then produce a csv file with the benchmark results. $ node benchmark/compare.js --old ./node-master --new ./node-pr-5134 string_decoder > compare-pr-5134.csv ``` -*Tips: there are some useful options of `benchmark/compare.js`. For example, +_Tips: there are some useful options of `benchmark/compare.js`. For example, if you want to compare the benchmark of a single script instead of a whole -module, you can use the `--filter` option:* +module, you can use the `--filter` option:_ ```console --new ./new-node-binary new node binary (required) @@ -347,7 +347,7 @@ $ cat compare-pr-5134.csv | sed '1p;/encoding='"'"ascii"'"'/!d' | Rscript benchm ... ``` -![compare tool boxplot](doc_img/compare-boxplot.png) +![compare tool boxplot](doc\_img/compare-boxplot.png) ### Comparing parameters @@ -427,7 +427,7 @@ chunkLen encoding rate confidence.interval 1024 utf8 2025551.2 81770.69 ``` -![compare tool boxplot](doc_img/scatter-plot.png) +![compare tool boxplot](doc\_img/scatter-plot.png) ### Running benchmarks on the CI diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index 1972c897b0a5eb..9884408af8553a 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -158,7 +158,7 @@ const timer = setTimeout(fail, common.platformTimeout(4000)); will create a 4-second timeout on most platforms but a longer timeout on slower platforms. -### The *common* API +### The _common_ API Make use of the helpers from the `common` module as much as possible. Please refer to the [common file documentation](https://github.com/nodejs/node/tree/HEAD/test/common) @@ -443,6 +443,7 @@ $ out/Release/cctest --gtest_filter=EnvironmentTest.AtExit\* ``` ### Node.js test fixture + There is a [test fixture][] named `node_test_fixture.h` which can be included by unit tests. The fixture takes care of setting up the Node.js environment and tearing it down after the tests have finished.