Nodejs/node
1
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2024-11-21 10:59:27 +00:00
Code Issues Actions 25 Packages Projects Releases Wiki Activity

doc: update markdown formatting for *.md files

Browse Source 
Fix formatting that will change when run through upcoming remark preset.

PR-URL: https://github.com/nodejs/node/pull/40154
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
This commit is contained in:
Rich Trott 2021-09-17 17:23:11 -07:00 committed by Node.js GitHub Bot
parent d05cca94ea
commit 549f96889a
5 changed files with 72 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
BUILDING.md
View File

@ -120,31 +120,31 @@ platforms. This is true regardless of entries in the table below.
| FreeBSD | x64 | >= 11 | Experimental | Downgraded as of Node.js 12 <sup>[7](#fn7)</sup> | | FreeBSD | x64 | >= 11 | Experimental | Downgraded as of Node.js 12 <sup>[7](#fn7)</sup> |
<em id="fn1">1</em>: GCC 8 is not provided on the base platform. Users will <em id="fn1">1</em>: GCC 8 is not provided on the base platform. Users will
need the need the
[Toolchain test builds PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=xenial) [Toolchain test builds PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=xenial)
or similar to source a newer compiler. or similar to source a newer compiler.
<em id="fn2">2</em>: GCC 8 is not provided on the base platform. Users will <em id="fn2">2</em>: GCC 8 is not provided on the base platform. Users will
need the need the
[devtoolset-8](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/) [devtoolset-8](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/)
or later to source a newer compiler. or later to source a newer compiler.
<em id="fn3">3</em>: Older kernel versions may work for ARM64. However the <em id="fn3">3</em>: Older kernel versions may work for ARM64. However the
Node.js test infrastructure only tests >= 4.5. Node.js test infrastructure only tests >= 4.5.
<em id="fn4">4</em>: On Windows, running Node.js in Windows terminal emulators <em id="fn4">4</em>: On Windows, running Node.js in Windows terminal emulators
like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty) like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty)
for the tty channels to work (e.g. `winpty node.exe script.js`). for the tty channels to work (e.g. `winpty node.exe script.js`).
In "Git bash" if you call the node shell alias (`node` without the `.exe` In "Git bash" if you call the node shell alias (`node` without the `.exe`
extension), `winpty` is used automatically. extension), `winpty` is used automatically.
<em id="fn5">5</em>: The Windows Subsystem for Linux (WSL) is not <em id="fn5">5</em>: The Windows Subsystem for Linux (WSL) is not
supported, but the GNU/Linux build process and binaries should work. The supported, but the GNU/Linux build process and binaries should work. The
community will only address issues that reproduce on native GNU/Linux community will only address issues that reproduce on native GNU/Linux
systems. Issues that only reproduce on WSL should be reported in the systems. Issues that only reproduce on WSL should be reported in the
[WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the [WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the
Windows binary (`node.exe`) in WSL is not recommended. It will not work Windows binary (`node.exe`) in WSL is not recommended. It will not work
without workarounds such as stdio redirection. without workarounds such as stdio redirection.
<em id="fn6">6</em>: Running Node.js on x86 Windows should work and binaries <em id="fn6">6</em>: Running Node.js on x86 Windows should work and binaries
are provided. However, tests in our infrastructure only run on WoW64. are provided. However, tests in our infrastructure only run on WoW64.
@ -195,7 +195,7 @@ Ubuntu 14.04 and Debian 8.
#### OpenSSL asm support #### OpenSSL asm support
OpenSSL-1.1.1 requires the following assembler version for use of asm OpenSSL-1.1.1 requires the following assembler version for use of asm
support on x86_64 and ia32. support on x86\_64 and ia32.
For use of AVX-512, For use of AVX-512,
@ -212,9 +212,9 @@ For use of AVX2,
* nasm version 2.10 or higher in Windows * nasm version 2.10 or higher in Windows
Please refer to Please refer to
<https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_ia32cap.html> for details. <https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_ia32cap.html> for details.
If compiling without one of the above, use `configure` with the If compiling without one of the above, use `configure` with the
`--openssl-no-asm` flag. Otherwise, `configure` will fail. `--openssl-no-asm` flag. Otherwise, `configure` will fail.
### Previous versions of this document ### Previous versions of this document
@ -232,6 +232,7 @@ Consult previous versions of this document for older versions of Node.js:
### Note about Python ### Note about Python
The Node.js project supports Python >= 3 for building and testing. The Node.js project supports Python >= 3 for building and testing.
### Unix and macOS ### Unix and macOS
#### Unix prerequisites #### Unix prerequisites
@ -480,7 +481,7 @@ release version is actually installed when you run `make install`.
To use the debug build with all the normal dependencies overwrite the release To use the debug build with all the normal dependencies overwrite the release
version in the install directory: version in the install directory:
``` console ```console
$ make install PREFIX=/opt/node-debug/ $ make install PREFIX=/opt/node-debug/
$ cp -a -f out/Debug/node /opt/node-debug/node $ cp -a -f out/Debug/node /opt/node-debug/node
``` ```
@ -496,7 +497,7 @@ was captured on (i.e. 64-bit `gdb` for `node` built on a 64-bit system, Linux
Example of generating a backtrace from the core dump: Example of generating a backtrace from the core dump:
``` console ```console
$ gdb /opt/node-debug/node core.node.8.1535359906 $ gdb /opt/node-debug/node core.node.8.1535359906
$ backtrace $ backtrace
``` ```
@ -507,12 +508,12 @@ $ backtrace
related bugs. ASAN builds are currently only supported on linux. related bugs. ASAN builds are currently only supported on linux.
If you want to check it on Windows or macOS or you want a consistent toolchain If you want to check it on Windows or macOS or you want a consistent toolchain
on Linux, you can try [Docker](https://www.docker.com/products/docker-desktop) on Linux, you can try [Docker](https://www.docker.com/products/docker-desktop)
(using an image like `gengjiawen/node-build:2020-02-14`). (using an image like `gengjiawen/node-build:2020-02-14`).
The `--debug` is not necessary and will slow down build and testing, but it can The `--debug` is not necessary and will slow down build and testing, but it can
show clear stacktrace if ASAN hits an issue. show clear stacktrace if ASAN hits an issue.
``` console ```console
$ ./configure --debug --enable-asan && make -j4 $ ./configure --debug --enable-asan && make -j4
$ make test-only $ make test-only
``` ```
@ -521,6 +522,7 @@ $ make test-only
If you plan to frequently rebuild Node.js, especially if using several branches, If you plan to frequently rebuild Node.js, especially if using several branches,
installing `ccache` can help to greatly reduce build times. Set up with: installing `ccache` can help to greatly reduce build times. Set up with:
```console ```console
$ sudo apt install ccache # for Debian/Ubuntu, included in most Linux distros $ sudo apt install ccache # for Debian/Ubuntu, included in most Linux distros
$ ccache -o cache_dir=<tmp_dir> $ ccache -o cache_dir=<tmp_dir>
@ -528,13 +530,16 @@ $ ccache -o max_size=5.0G
$ export CC="ccache gcc" # add to your .profile $ export CC="ccache gcc" # add to your .profile
$ export CXX="ccache g++" # add to your .profile $ export CXX="ccache g++" # add to your .profile
``` ```
This will allow for near-instantaneous rebuilds even when switching branches. This will allow for near-instantaneous rebuilds even when switching branches.
When modifying only the JS layer in `lib`, it is possible to externally load it When modifying only the JS layer in `lib`, it is possible to externally load it
without modifying the executable: without modifying the executable:
```console ```console
$ ./configure --node-builtin-modules-path $(pwd) $ ./configure --node-builtin-modules-path $(pwd)
``` ```
The resulting binary won't include any JS files and will try to load them from The resulting binary won't include any JS files and will try to load them from
the specified directory. The JS debugger of Visual Studio Code supports this the specified directory. The JS debugger of Visual Studio Code supports this
configuration since the November 2020 version and allows for setting configuration since the November 2020 version and allows for setting
@ -678,7 +683,7 @@ $ ./configure --with-intl=full-icu
### Trimmed: `small-icu` (English only) support ### Trimmed: `small-icu` (English only) support
In this configuration, only English data is included, but In this configuration, only English data is included, but
the full `Intl` (ECMA-402) APIs. It does not need to download the full `Intl` (ECMA-402) APIs. It does not need to download
any dependencies to function. You can add full data at runtime. any dependencies to function. You can add full data at runtime.
@ -774,6 +779,7 @@ If you want to build Node.js using openssl-3.0.0+quic, you can follow these
steps: steps:
**clone OpenSSL source and prepare build** **clone OpenSSL source and prepare build**
```bash ```bash
git clone git@github.com:quictls/openssl.git git clone git@github.com:quictls/openssl.git
@ -791,6 +797,7 @@ will publish the OpenSSL libraries and such. We will also use this path
(and sub-paths) later when compiling Node.js. (and sub-paths) later when compiling Node.js.
**compile and install OpenSSL** **compile and install OpenSSL**
```console ```console
make -j8 make -j8
make install make install
@ -806,6 +813,7 @@ find the `fipsmodule.cnf` file - let's add the following to the end of the
`openssl.cnf` file. `openssl.cnf` file.
**alter openssl.cnf** **alter openssl.cnf**
```text ```text
.include fipsmodule.cnf .include fipsmodule.cnf
@ -826,6 +834,7 @@ sure that you specify an absolute path for the `.include fipsmodule.cnf` line -
using relative paths did not work on my system! using relative paths did not work on my system!
**alter openssl.cnf using a script** **alter openssl.cnf using a script**
```console ```console
cat <<EOT >> /path/to/install/dir/ssl/openssl.cnf cat <<EOT >> /path/to/install/dir/ssl/openssl.cnf
.include /path/to/install/dir/ssl/fipsmodule.cnf .include /path/to/install/dir/ssl/fipsmodule.cnf
@ -845,12 +854,14 @@ EOT
As you might have picked a non-custom path for your OpenSSL install dir, we As you might have picked a non-custom path for your OpenSSL install dir, we
have to export the following two environment variables in order for Node.js to have to export the following two environment variables in order for Node.js to
find our OpenSSL modules we built beforehand: find our OpenSSL modules we built beforehand:
```console ```console
export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf
export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules
``` ```
**build Node.js** **build Node.js**
```console ```console
./configure \ ./configure \
--shared-openssl \ --shared-openssl \
@ -865,6 +876,7 @@ make -j8
``` ```
**verify the produced executable** **verify the produced executable**
```console ```console
ldd ./node ldd ./node
linux-vdso.so.1 (0x00007ffd7917b000) linux-vdso.so.1 (0x00007ffd7917b000)
@ -884,12 +896,14 @@ If the `ldd` command says that `libcrypto` cannot be found one needs to set
`--shared-openssl-libpath` (see previous step). `--shared-openssl-libpath` (see previous step).
**verify the OpenSSL version** **verify the OpenSSL version**
```console ```console
./node -p process.versions.openssl ./node -p process.versions.openssl
3.0.0-alpha16+quic 3.0.0-alpha16+quic
``` ```
**verify that FIPS is available** **verify that FIPS is available**
```console ```console
./node -p 'process.config.variables.openssl_is_fips' ./node -p 'process.config.variables.openssl_is_fips'
true true
@ -905,13 +919,16 @@ executable. See sections
[Enabling FIPS using OpenSSL config](#enabling-fips-using-openssl-config) below. [Enabling FIPS using OpenSSL config](#enabling-fips-using-openssl-config) below.
### Enabling FIPS using Node.js options ### Enabling FIPS using Node.js options
This is done using one of the Node.js options `--enable-fips` or This is done using one of the Node.js options `--enable-fips` or
`--force-fips`, for example: `--force-fips`, for example:
```console ```console
$ node --enable-fips -p 'crypto.getFips()' $ node --enable-fips -p 'crypto.getFips()'
``` ```
### Enabling FIPS using OpenSSL config ### Enabling FIPS using OpenSSL config
This example show that using OpenSSL's configuration file, FIPS can be enabled This example show that using OpenSSL's configuration file, FIPS can be enabled
without specifying the `--enable-fips` or `--force-fips` options by setting without specifying the `--enable-fips` or `--force-fips` options by setting
`default_properties = fips=yes` in the FIPS configuration file. See `default_properties = fips=yes` in the FIPS configuration file. See
@ -920,6 +937,7 @@ for details.
For this to work the OpenSSL configuration file (default openssl.cnf) needs to For this to work the OpenSSL configuration file (default openssl.cnf) needs to
be updated. The following shows an example: be updated. The following shows an example:
```console ```console
openssl_conf = openssl_init openssl_conf = openssl_init
@ -939,6 +957,7 @@ activate = 1
[algorithm_sect] [algorithm_sect]
default_properties = fips=yes default_properties = fips=yes
``` ```
After this change Node.js can be run without the `--enable-fips` or `--force-fips` After this change Node.js can be run without the `--enable-fips` or `--force-fips`
options. options.

8
CHANGELOG.md
View File

@ -24,6 +24,7 @@ Please use the following table to find the changelog for a specific Node.js
release. release.
<!--lint disable maximum-line-length--> <!--lint disable maximum-line-length-->
<table> <table>
<tr> <tr>
<th title="Current"><a href="doc/changelogs/CHANGELOG_V16.md">16</a><sup>Current</sup></th> <th title="Current"><a href="doc/changelogs/CHANGELOG_V16.md">16</a><sup>Current</sup></th>
@ -138,8 +139,9 @@ release.
LTS releases. LTS releases.
* Release versions in **bold** text are the most recent supported releases. * Release versions in **bold** text are the most recent supported releases.
---- ***
----
***
## 2016-05-06, Version 0.12.14 (Maintenance), @rvagg ## 2016-05-06, Version 0.12.14 (Maintenance), @rvagg
@ -1355,7 +1357,7 @@ release.
## 2009.08.21, Version 0.1.5 ## 2009.08.21, Version 0.1.5
<a href="doc/changelogs/CHANGELOG_ARCHIVE.md#0.1.5>Moved to doc/changelogs/CHANGELOG_V6.md#6.0.0</a>. <a href="doc/changelogs/CHANGELOG_ARCHIVE.md#0.1.5">Moved to doc/changelogs/CHANGELOG_V6.md#6.0.0</a>.
## 2009.08.13, Version 0.1.4 ## 2009.08.13, Version 0.1.4

3
CONTRIBUTING.md
View File

@ -29,8 +29,10 @@ See [details on our policy on Code of Conduct](./doc/guides/contributing/code-of
* [Notes](./doc/guides/contributing/pull-requests.md#notes) * [Notes](./doc/guides/contributing/pull-requests.md#notes)
<a id="developers-certificate-of-origin"></a> <a id="developers-certificate-of-origin"></a>
## Developer's Certificate of Origin 1.1 ## Developer's Certificate of Origin 1.1
<pre>
By making a contribution to this project, I certify that: By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I (a) The contribution was created in whole or in part by me and I
@ -54,3 +56,4 @@ By making a contribution to this project, I certify that:
personal information I submit with it, including my sign-off) is personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved. this project or the open source license(s) involved.
</pre>

4
GOVERNANCE.md
View File

@ -153,8 +153,8 @@ the nomination fails.
There are steps a nominator can take in advance to make a nomination as There are steps a nominator can take in advance to make a nomination as
frictionless as possible. To request feedback from other collaborators in frictionless as possible. To request feedback from other collaborators in
private, use the [collaborators discussion page][] private, use the [collaborators discussion page][]
(which only collaborators may view). A nominator may also work with the (which only collaborators may view). A nominator may also work with the
nominee to improve their contribution profile. nominee to improve their contribution profile.
Collaborators might overlook someone with valuable contributions. In that case, Collaborators might overlook someone with valuable contributions. In that case,

28
onboarding.md
View File

@ -51,12 +51,13 @@ onboarding session.
[Publicizing or hiding organization membership][]. [Publicizing or hiding organization membership][].
* Notifications: * Notifications:
* Use [https://github.com/notifications](https://github.com/notifications) or * Use <https://github.com/notifications> or
set up email set up email
* Watching the main repository will flood your inbox (several hundred * Watching the main repository will flood your inbox (several hundred
notifications on typical weekdays), so be prepared notifications on typical weekdays), so be prepared
The project has two venues for real-time discussion: The project has two venues for real-time discussion:
* [`#nodejs-dev`](https://openjs-foundation.slack.com/archives/C019Y2T6STH) on * [`#nodejs-dev`](https://openjs-foundation.slack.com/archives/C019Y2T6STH) on
the [OpenJS Foundation](https://slack-invite.openjsf.org/) the [OpenJS Foundation](https://slack-invite.openjsf.org/)
@ -71,7 +72,7 @@ The project has two venues for real-time discussion:
* The best outcome is for people who come to our issue tracker to feel like * The best outcome is for people who come to our issue tracker to feel like
they can come back again. they can come back again.
* You are expected to follow *and* hold others accountable to the * You are expected to follow _and_ hold others accountable to the
[Code of Conduct][]. [Code of Conduct][].
## Managing the issue tracker ## Managing the issue tracker
@ -88,7 +89,7 @@ The project has two venues for real-time discussion:
not perfect, of course. Feel free to apply relevant labels and remove not perfect, of course. Feel free to apply relevant labels and remove
irrelevant labels from pull requests and issues. irrelevant labels from pull requests and issues.
* `semver-{minor,major}`: * `semver-{minor,major}`:
* If a change has the remote *chance* of breaking something, use the * If a change has the remote _chance_ of breaking something, use the
`semver-major` label `semver-major` label
* When adding a `semver-*` label, add a comment explaining why you're adding * When adding a `semver-*` label, add a comment explaining why you're adding
it. Do it right away so you don't forget! it. Do it right away so you don't forget!
@ -113,20 +114,26 @@ The project has two venues for real-time discussion:
## Reviewing pull requests ## Reviewing pull requests
* The primary goal is for the codebase to improve. * The primary goal is for the codebase to improve.
* Secondary (but not far off) is for the person submitting code to succeed. A * Secondary (but not far off) is for the person submitting code to succeed. A
pull request from a new contributor is an opportunity to grow the community. pull request from a new contributor is an opportunity to grow the community.
* Review a bit at a time. Do not overwhelm new contributors. * Review a bit at a time. Do not overwhelm new contributors.
* It is tempting to micro-optimize. Don't succumb to that temptation. We * It is tempting to micro-optimize. Don't succumb to that temptation. We
change V8 often. Techniques that provide improved performance today may be change V8 often. Techniques that provide improved performance today may be
unnecessary in the future. unnecessary in the future.
* Be aware: Your opinion carries a lot of weight! * Be aware: Your opinion carries a lot of weight!
* Nits (requests for small changes that are not essential) are fine, but try to * Nits (requests for small changes that are not essential) are fine, but try to
avoid stalling the pull request. avoid stalling the pull request.
* Identify them as nits when you comment: `Nit: change foo() to bar().` * Identify them as nits when you comment: `Nit: change foo() to bar().`
* If they are stalling the pull request, fix them yourself on merge. * If they are stalling the pull request, fix them yourself on merge.
* Insofar as possible, issues should be identified by tools rather than human * Insofar as possible, issues should be identified by tools rather than human
reviewers. If you are leaving comments about issues that could be identified reviewers. If you are leaving comments about issues that could be identified
by tools but are not, consider implementing the necessary tooling. by tools but are not, consider implementing the necessary tooling.
* Minimum wait for comments time * Minimum wait for comments time
* There is a minimum waiting time which we try to respect for non-trivial * There is a minimum waiting time which we try to respect for non-trivial
changes so that people who may have important input in such a distributed changes so that people who may have important input in such a distributed
@ -134,6 +141,7 @@ The project has two venues for real-time discussion:
* For non-trivial changes, leave the pull request open for at least 48 hours. * For non-trivial changes, leave the pull request open for at least 48 hours.
* If a pull request is abandoned, check if they'd mind if you took it over * If a pull request is abandoned, check if they'd mind if you took it over
(especially if it just has nits left). (especially if it just has nits left).
* Approving a change * Approving a change
* Collaborators indicate that they have reviewed and approve of the changes in * Collaborators indicate that they have reviewed and approve of the changes in
a pull request using GitHub’s approval interface a pull request using GitHub’s approval interface
@ -159,7 +167,7 @@ The project has two venues for real-time discussion:
such as `async_hooks`. such as `async_hooks`.
* Continuous Integration (CI) Testing: * Continuous Integration (CI) Testing:
* [https://ci.nodejs.org/](https://ci.nodejs.org/) * <https://ci.nodejs.org/>
* It is not automatically run. You need to start it manually. * It is not automatically run. You need to start it manually.
* Log in on CI is integrated with GitHub. Try to log in now! * Log in on CI is integrated with GitHub. Try to log in now!
* You will be using `node-test-pull-request` most of the time. Go there now! * You will be using `node-test-pull-request` most of the time. Go there now!
@ -228,12 +236,12 @@ needs to be pointed out separately during the onboarding.
* Almost any mistake you could make can be fixed or reverted. * Almost any mistake you could make can be fixed or reverted.
* The existing collaborators trust you and are grateful for your help! * The existing collaborators trust you and are grateful for your help!
* Other repositories: * Other repositories:
* [https://github.com/nodejs/TSC](https://github.com/nodejs/TSC) * <https://github.com/nodejs/TSC>
* [https://github.com/nodejs/build](https://github.com/nodejs/build) * <https://github.com/nodejs/build>
* [https://github.com/nodejs/nodejs.org](https://github.com/nodejs/nodejs.org) * <https://github.com/nodejs/nodejs.org>
* [https://github.com/nodejs/readable-stream](https://github.com/nodejs/readable-stream) * <https://github.com/nodejs/readable-stream>
* [https://github.com/nodejs/LTS](https://github.com/nodejs/LTS) * <https://github.com/nodejs/LTS>
* [https://github.com/nodejs/citgm](https://github.com/nodejs/citgm) * <https://github.com/nodejs/citgm>
* The OpenJS Foundation hosts regular summits for active contributors to the * The OpenJS Foundation hosts regular summits for active contributors to the
Node.js project, where we have face-to-face discussions about our work on the Node.js project, where we have face-to-face discussions about our work on the
project. The Foundation has travel funds to cover participants' expenses project. The Foundation has travel funds to cover participants' expenses