diff options
| -rw-r--r-- | BUILDING.md | 69 | ||||
| -rw-r--r-- | CHANGELOG.md | 8 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 3 | ||||
| -rw-r--r-- | GOVERNANCE.md | 4 | ||||
| -rw-r--r-- | onboarding.md | 28 |
5 files changed, 72 insertions, 40 deletions
diff --git a/BUILDING.md b/BUILDING.md index 06cfaff605..cdc3ac4246 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -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> | <em id="fn1">1</em>: GCC 8 is not provided on the base platform. Users will - need the - [Toolchain test builds PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=xenial) - or similar to source a newer compiler. +need the +[Toolchain test builds PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=xenial) +or similar to source a newer compiler. <em id="fn2">2</em>: GCC 8 is not provided on the base platform. Users will - need the - [devtoolset-8](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/) - or later to source a newer compiler. +need the +[devtoolset-8](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/) +or later to source a newer compiler. <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 - 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`). - In "Git bash" if you call the node shell alias (`node` without the `.exe` - extension), `winpty` is used automatically. +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`). +In "Git bash" if you call the node shell alias (`node` without the `.exe` +extension), `winpty` is used automatically. <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 - community will only address issues that reproduce on native GNU/Linux - systems. Issues that only reproduce on WSL should be reported in 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 - without workarounds such as stdio redirection. +supported, but the GNU/Linux build process and binaries should work. The +community will only address issues that reproduce on native GNU/Linux +systems. Issues that only reproduce on WSL should be reported in 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 +without workarounds such as stdio redirection. <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. @@ -195,7 +195,7 @@ Ubuntu 14.04 and Debian 8. #### OpenSSL asm support 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, @@ -212,9 +212,9 @@ For use of AVX2, * nasm version 2.10 or higher in Windows 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. ### Previous versions of this document @@ -232,6 +232,7 @@ Consult previous versions of this document for older versions of Node.js: ### Note about Python The Node.js project supports Python >= 3 for building and testing. + ### Unix and macOS #### 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 version in the install directory: -``` console +```console $ make install PREFIX=/opt/node-debug/ $ 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: -``` console +```console $ gdb /opt/node-debug/node core.node.8.1535359906 $ backtrace ``` @@ -507,12 +508,12 @@ $ backtrace 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 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 show clear stacktrace if ASAN hits an issue. -``` console +```console $ ./configure --debug --enable-asan && make -j4 $ make test-only ``` @@ -521,6 +522,7 @@ $ make test-only 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: + ```console $ sudo apt install ccache # for Debian/Ubuntu, included in most Linux distros $ 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 CXX="ccache g++" # add to your .profile ``` + 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 without modifying the executable: + ```console $ ./configure --node-builtin-modules-path $(pwd) ``` + 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 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 - 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 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: **clone OpenSSL source and prepare build** + ```bash 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. **compile and install OpenSSL** + ```console make -j8 make install @@ -806,6 +813,7 @@ find the `fipsmodule.cnf` file - let's add the following to the end of the `openssl.cnf` file. **alter openssl.cnf** + ```text .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! **alter openssl.cnf using a script** + ```console cat <<EOT >> /path/to/install/dir/ssl/openssl.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 have to export the following two environment variables in order for Node.js to find our OpenSSL modules we built beforehand: + ```console export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules ``` **build Node.js** + ```console ./configure \ --shared-openssl \ @@ -865,6 +876,7 @@ make -j8 ``` **verify the produced executable** + ```console ldd ./node 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). **verify the OpenSSL version** + ```console ./node -p process.versions.openssl 3.0.0-alpha16+quic ``` **verify that FIPS is available** + ```console ./node -p 'process.config.variables.openssl_is_fips' true @@ -905,13 +919,16 @@ executable. See sections [Enabling FIPS using OpenSSL config](#enabling-fips-using-openssl-config) below. ### Enabling FIPS using Node.js options + This is done using one of the Node.js options `--enable-fips` or `--force-fips`, for example: + ```console $ node --enable-fips -p 'crypto.getFips()' ``` ### Enabling FIPS using OpenSSL config + This example show that using OpenSSL's configuration file, FIPS can be enabled without specifying the `--enable-fips` or `--force-fips` options by setting `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 be updated. The following shows an example: + ```console openssl_conf = openssl_init @@ -939,6 +957,7 @@ activate = 1 [algorithm_sect] default_properties = fips=yes ``` + After this change Node.js can be run without the `--enable-fips` or `--force-fips` options. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b9d45bae3..14abca5112 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,7 @@ Please use the following table to find the changelog for a specific Node.js release. <!--lint disable maximum-line-length--> + <table> <tr> <th title="Current"><a href="doc/changelogs/CHANGELOG_V16.md">16</a><sup>Current</sup></th> @@ -138,8 +139,9 @@ release. LTS releases. * Release versions in **bold** text are the most recent supported releases. ----- ----- +*** + +*** ## 2016-05-06, Version 0.12.14 (Maintenance), @rvagg @@ -1355,7 +1357,7 @@ release. ## 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30db8cf9b1..d0d3f4f648 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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) <a id="developers-certificate-of-origin"></a> + ## Developer's Certificate of Origin 1.1 +<pre> By making a contribution to this project, I certify that: (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 maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. +</pre> diff --git a/GOVERNANCE.md b/GOVERNANCE.md index aa73e4b3ee..37ce1576cf 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -153,8 +153,8 @@ the nomination fails. There are steps a nominator can take in advance to make a nomination as frictionless as possible. To request feedback from other collaborators in - private, use the [collaborators discussion page][] - (which only collaborators may view). A nominator may also work with the +private, use the [collaborators discussion page][] +(which only collaborators may view). A nominator may also work with the nominee to improve their contribution profile. Collaborators might overlook someone with valuable contributions. In that case, diff --git a/onboarding.md b/onboarding.md index ae65f07f37..d74600dcce 100644 --- a/onboarding.md +++ b/onboarding.md @@ -51,12 +51,13 @@ onboarding session. [Publicizing or hiding organization membership][]. * Notifications: - * Use [https://github.com/notifications](https://github.com/notifications) or + * Use <https://github.com/notifications> or set up email * Watching the main repository will flood your inbox (several hundred notifications on typical weekdays), so be prepared The project has two venues for real-time discussion: + * [`#nodejs-dev`](https://openjs-foundation.slack.com/archives/C019Y2T6STH) on 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 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][]. ## 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 irrelevant labels from pull requests and issues. * `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 * When adding a `semver-*` label, add a comment explaining why you're adding 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 * The primary goal is for the codebase to improve. + * 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. + * Review a bit at a time. Do not overwhelm new contributors. * It is tempting to micro-optimize. Don't succumb to that temptation. We change V8 often. Techniques that provide improved performance today may be unnecessary in the future. + * Be aware: Your opinion carries a lot of weight! + * Nits (requests for small changes that are not essential) are fine, but try to avoid stalling the pull request. * Identify them as nits when you comment: `Nit: change foo() to bar().` * If they are stalling the pull request, fix them yourself on merge. + * Insofar as possible, issues should be identified by tools rather than human reviewers. If you are leaving comments about issues that could be identified by tools but are not, consider implementing the necessary tooling. + * Minimum wait for comments time * 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 @@ -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. * If a pull request is abandoned, check if they'd mind if you took it over (especially if it just has nits left). + * Approving a change * Collaborators indicate that they have reviewed and approve of the changes in 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`. * 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. * 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! @@ -228,12 +236,12 @@ needs to be pointed out separately during the onboarding. * Almost any mistake you could make can be fixed or reverted. * The existing collaborators trust you and are grateful for your help! * Other repositories: - * [https://github.com/nodejs/TSC](https://github.com/nodejs/TSC) - * [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/readable-stream](https://github.com/nodejs/readable-stream) - * [https://github.com/nodejs/LTS](https://github.com/nodejs/LTS) - * [https://github.com/nodejs/citgm](https://github.com/nodejs/citgm) + * <https://github.com/nodejs/TSC> + * <https://github.com/nodejs/build> + * <https://github.com/nodejs/nodejs.org> + * <https://github.com/nodejs/readable-stream> + * <https://github.com/nodejs/LTS> + * <https://github.com/nodejs/citgm> * 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 project. The Foundation has travel funds to cover participants' expenses |