From 260092eca316bae6036e52b2cdc73c4c4f8a9da6 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 20 May 2023 00:14:03 +0200 Subject: [PATCH] doc: harmonize fenced code snippet flags We had a few code snippets that were using a non-descriptive tag (e.g. `console` or `text`), whereas the actual language it's using describes it better, and improves the syntax highlighting. This commit also removes non-necessary leading chars (e.g. `$`, `>`, or `%`) to make it easier for readers to copy and paste to try the command themselves. PR-URL: https://github.com/nodejs/node/pull/48082 Reviewed-By: Rich Trott Reviewed-By: Darshan Sen Reviewed-By: Paolo Insogna Reviewed-By: Luigi Pinca --- BUILDING.md | 196 ++++++++--------- README.md | 16 +- doc/api/addons.md | 4 +- doc/api/cli.md | 30 +-- doc/api/esm.md | 2 +- doc/api/net.md | 8 +- doc/api/process.md | 12 +- doc/api/repl.md | 2 +- doc/api/single-executable-applications.md | 52 ++--- doc/api/synopsis.md | 22 +- doc/api/tls.md | 4 +- doc/api/wasi.md | 4 +- doc/contributing/collaborator-guide.md | 52 ++--- .../investigating-native-memory-leaks.md | 12 +- .../maintaining/maintaining-V8.md | 2 +- .../maintaining/maintaining-openssl.md | 42 ++-- doc/contributing/pull-requests.md | 22 +- doc/contributing/releases-node-api.md | 20 +- doc/contributing/releases.md | 202 +++++++++--------- .../writing-and-running-benchmarks.md | 26 +-- doc/contributing/writing-tests.md | 14 +- test/wasi/README.md | 4 +- test/wpt/README.md | 14 +- 23 files changed, 381 insertions(+), 381 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index f5a646eade3973..ff101422f7ab32 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -261,9 +261,9 @@ fail. To build Node.js: -```console -$ ./configure -$ make -j4 +```bash +./configure +make -j4 ``` We can speed up the builds by using [Ninja](https://ninja-build.org/). For more @@ -284,8 +284,8 @@ Running the following script on macOS will add the firewall rules for the executable `node` in the `out` directory and the symbolic `node` link in the project's root directory. -```console -$ sudo ./tools/macos-firewall.sh +```bash +sudo ./tools/macos-firewall.sh ``` #### Installing Node.js @@ -300,16 +300,16 @@ To install this version of Node.js into a system directory: To verify the build: -```console -$ make test-only +```bash +make test-only ``` At this point, you are ready to make code changes and re-run the tests. If you are running tests before submitting a pull request, use: -```console -$ make -j4 test +```bash +make -j4 test ``` `make -j4 test` does a full check on the codebase, including running linters and @@ -321,29 +321,29 @@ To run the linter without running tests, use If you are updating tests and want to run tests in a single test file (e.g. `test/parallel/test-stream2-transform.js`): -```text -$ tools/test.py test/parallel/test-stream2-transform.js +```bash +tools/test.py test/parallel/test-stream2-transform.js ``` You can execute the entire suite of tests for a given subsystem by providing the name of a subsystem: -```text -$ tools/test.py child-process +```bash +tools/test.py child-process ``` You can also execute the tests in a test suite directory (such as `test/message`): -```text -$ tools/test.py test/message +```bash +tools/test.py test/message ``` If you want to check the other options, please refer to the help by using the `--help` option: -```text -$ tools/test.py --help +```bash +tools/test.py --help ``` > Note: On Windows you should use `python3` executable. @@ -351,8 +351,8 @@ $ tools/test.py --help You can usually run tests directly with node: -```text -$ ./node test/parallel/test-stream2-transform.js +```bash +./node test/parallel/test-stream2-transform.js ``` > Info: `./node` points to your local Node.js build. @@ -379,9 +379,9 @@ to run/debug tests if your IDE configs are present. It's good practice to ensure any code you add or change is covered by tests. You can do so by running the test suite with coverage enabled: -```console -$ ./configure --coverage -$ make coverage +```bash +./configure --coverage +make coverage ``` A detailed coverage report will be written to `coverage/index.html` for @@ -391,33 +391,33 @@ If you only want to run the JavaScript tests then you do not need to run the first command (`./configure --coverage`). Run `make coverage-run-js`, to execute JavaScript tests independently of the C++ test suite: -```text -$ make coverage-run-js +```bash +make coverage-run-js ``` If you are updating tests and want to collect coverage for a single test file (e.g. `test/parallel/test-stream2-transform.js`): -```text -$ make coverage-clean -$ NODE_V8_COVERAGE=coverage/tmp tools/test.py test/parallel/test-stream2-transform.js -$ make coverage-report-js +```bash +make coverage-clean +NODE_V8_COVERAGE=coverage/tmp tools/test.py test/parallel/test-stream2-transform.js +make coverage-report-js ``` You can collect coverage for the entire suite of tests for a given subsystem by providing the name of a subsystem: -```text -$ make coverage-clean -$ NODE_V8_COVERAGE=coverage/tmp tools/test.py --mode=release child-process -$ make coverage-report-js +```bash +make coverage-clean +NODE_V8_COVERAGE=coverage/tmp tools/test.py --mode=release child-process +make coverage-report-js ``` The `make coverage` command downloads some tools to the project root directory. To clean up after generating the coverage reports: -```console -$ make coverage-clean +```bash +make coverage-clean ``` #### Building the documentation @@ -473,9 +473,9 @@ If you run into an issue where the information provided by the JS stack trace is not enough, or if you suspect the error happens outside of the JS VM, you can try to build a debug enabled binary: -```console -$ ./configure --debug -$ make -j4 +```bash +./configure --debug +make -j4 ``` `make` with `./configure --debug` generates two binaries, the regular release @@ -485,9 +485,9 @@ 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 -$ make install PREFIX=/opt/node-debug/ -$ cp -a -f out/Debug/node /opt/node-debug/node +```bash +make install PREFIX=/opt/node-debug/ +cp -a -f out/Debug/node /opt/node-debug/node ``` When using the debug binary, core dumps will be generated in case of crashes. @@ -501,9 +501,9 @@ 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 +```bash $ gdb /opt/node-debug/node core.node.8.1535359906 -$ backtrace +(gdb) backtrace ``` #### Building an ASan build @@ -517,9 +517,9 @@ on Linux, you can try [Docker](https://www.docker.com/products/docker-desktop) The `--debug` is not necessary and will slow down build and testing, but it can show clear stacktrace if ASan hits an issue. -```console -$ ./configure --debug --enable-asan && make -j4 -$ make test-only +```bash +./configure --debug --enable-asan && make -j4 +make test-only ``` #### Speeding up frequent rebuilds when developing @@ -548,8 +548,8 @@ 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)" +```bash +./configure --node-builtin-modules-path "$(pwd)" ``` The resulting binary won't include any JS files and will try to load them from @@ -638,20 +638,20 @@ disk space. If the path to your build directory contains a space or a non-ASCII character, the build will likely fail. -```console -> .\vcbuild +```powershell +.\vcbuild ``` To run the tests: -```console -> .\vcbuild test +```powershell +.\vcbuild test ``` To test if Node.js was built correctly: -```console -> Release\node -e "console.log('Hello from Node.js', process.version)" +```powershell +Release\node -e "console.log('Hello from Node.js', process.version)" ``` ### Android @@ -665,9 +665,9 @@ Be sure you have downloaded and extracted [Android NDK](https://developer.android.com/ndk) before in a folder. Then run: -```console -$ ./android-configure -$ make -j4 +```bash +./android-configure +make -j4 ``` The Android SDK version should be at least 24 (Android 7.0) and the target @@ -684,14 +684,14 @@ This is the default option. #### Unix/macOS -```console -$ ./configure --with-intl=full-icu +```bash +./configure --with-intl=full-icu ``` #### Windows -```console -> .\vcbuild full-icu +```powershell +.\vcbuild full-icu ``` ### Trimmed: `small-icu` (English only) support @@ -702,14 +702,14 @@ any dependencies to function. You can add full data at runtime. #### Unix/macOS -```console -$ ./configure --with-intl=small-icu +```bash +./configure --with-intl=small-icu ``` #### Windows -```console -> .\vcbuild small-icu +```powershell +.\vcbuild small-icu ``` ### Building without Intl support @@ -719,20 +719,20 @@ The `Intl` object will not be available, nor some other APIs such as #### Unix/macOS -```console -$ ./configure --without-intl +```bash +./configure --without-intl ``` #### Windows -```console -> .\vcbuild without-intl +```powershell +.\vcbuild without-intl ``` ### Use existing installed ICU (Unix/macOS only) -```console -$ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu +```bash +pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu ``` If you are cross-compiling, your `pkg-config` must be able to supply a path @@ -753,20 +753,20 @@ during configuration if the ICU version is too old. From an already-unpacked ICU: -```console -$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu +```bash +./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu ``` From a local ICU tarball: -```console -$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz +```bash +./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz ``` From a tarball URL: -```console -$ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz +```bash +./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz ``` #### Windows @@ -775,8 +775,8 @@ First unpack latest ICU to `deps/icu` [icu4c-**##.#**-src.tgz](http://site.icu-project.org/download) (or `.zip`) as `deps/icu` (You'll have: `deps/icu/source/...`) -```console -> .\vcbuild full-icu +```powershell +.\vcbuild full-icu ``` ### Configure OpenSSL appname @@ -788,8 +788,8 @@ configuration file `openssl.cnf`. Node.js will only read a section that is by default named `nodejs_conf`, but this name can be overridden using the following configure option: -```console -$ ./configure --openssl-conf-name= +```bash +./configure --openssl-conf-name= ``` ## Building Node.js with FIPS-compliant OpenSSL @@ -802,9 +802,9 @@ dynamically linking with OpenSSL 3.0.0 by using the configuration flag FIPS can be supported by specifying the configuration flag `--openssl-is-fips`: -```console -$ ./configure --openssl-is-fips -$ make -j8 +```bash +./configure --openssl-is-fips +make -j8 ``` The above command will build and install the FIPS module into the out directory. @@ -872,7 +872,7 @@ will publish the OpenSSL libraries and such. We will also use this path **compile and install OpenSSL** -```console +```bash make -j8 make install make install_ssldirs @@ -909,7 +909,7 @@ using relative paths did not work on my system! **alter openssl.cnf using a script** -```console +```bash cat <> /path/to/install/dir/ssl/openssl.cnf .include /path/to/install/dir/ssl/fipsmodule.cnf @@ -929,14 +929,14 @@ 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 +```bash export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules ``` **build Node.js** -```console +```bash ./configure \ --shared-openssl \ --shared-openssl-libpath=/path/to/install/dir/lib \ @@ -952,7 +952,7 @@ make -j8 **verify the produced executable** ```console -ldd ./node +$ ldd ./node linux-vdso.so.1 (0x00007ffd7917b000) libcrypto.so.81.3 => /path/to/install/dir/lib/libcrypto.so.81.3 (0x00007fd911321000) libssl.so.81.3 => /path/to/install/dir/lib/libssl.so.81.3 (0x00007fd91125e000) @@ -972,17 +972,17 @@ If the `ldd` command says that `libcrypto` cannot be found one needs to set **verify the OpenSSL version** ```console -./node -p process.versions.openssl +$ ./node -p process.versions.openssl 3.0.0-alpha16+quic ``` **verify that FIPS is available** ```console -./node -p 'process.config.variables.openssl_is_fips' +$ ./node -p 'process.config.variables.openssl_is_fips' true -./node --enable-fips -p 'crypto.getFips()' +$ ./node --enable-fips -p 'crypto.getFips()' 1 ``` @@ -997,8 +997,8 @@ executable. See sections This is done using one of the Node.js options `--enable-fips` or `--force-fips`, for example: -```console -$ node --enable-fips -p 'crypto.getFips()' +```bash +node --enable-fips -p 'crypto.getFips()' ``` ### Enabling FIPS using OpenSSL config @@ -1012,7 +1012,7 @@ for details. For this to work the OpenSSL configuration file (default openssl.cnf) needs to be updated. The following shows an example: -```console +```text openssl_conf = openssl_init .include /path/to/install/dir/ssl/fipsmodule.cnf @@ -1046,8 +1046,8 @@ This command will make `/root/myModule.js` available via `require('/root/myModule')` and `./myModule2.js` available via `require('myModule2')`. -```console -$ ./configure --link-module '/root/myModule.js' --link-module './myModule2.js' +```bash +./configure --link-module '/root/myModule.js' --link-module './myModule2.js' ``` ### Windows @@ -1055,8 +1055,8 @@ $ ./configure --link-module '/root/myModule.js' --link-module './myModule2.js' To make `./myModule.js` available via `require('myModule')` and `./myModule2.js` available via `require('myModule2')`: -```console -> .\vcbuild link-module './myModule.js' link-module './myModule2.js' +```powershell +.\vcbuild link-module './myModule.js' link-module './myModule2.js' ``` ## Building to use shared dependencies at runtime diff --git a/README.md b/README.md index e2a7968f45b212..9a68f4b0615cfe 100644 --- a/README.md +++ b/README.md @@ -98,15 +98,15 @@ files. To download `SHASUMS256.txt` using `curl`: -```console -$ curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt +```bash +curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt ``` To check that a downloaded file matches the checksum, run it through `sha256sum` with a command such as: -```console -$ grep node-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c - +```bash +grep node-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c - ``` For Current and LTS, the GPG detached signature of `SHASUMS256.txt` is in @@ -115,16 +115,16 @@ For Current and LTS, the GPG detached signature of `SHASUMS256.txt` is in [the GPG keys of individuals authorized to create releases](#release-keys). To import the keys: -```console -$ gpg --keyserver hkps://keys.openpgp.org --recv-keys 4ED778F539E3634C779C87C6D7062848A1AB005C +```bash +gpg --keyserver hkps://keys.openpgp.org --recv-keys 4ED778F539E3634C779C87C6D7062848A1AB005C ``` See [Release keys](#release-keys) for a script to import active release keys. Next, download the `SHASUMS256.txt.sig` for the release: -```console -$ curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt.sig +```bash +curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt.sig ``` Then use `gpg --verify SHASUMS256.txt.sig SHASUMS256.txt` to verify diff --git a/doc/api/addons.md b/doc/api/addons.md index 4075158e2ae750..a2d22ae71987aa 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -532,8 +532,8 @@ filename to the `sources` array: Once the `binding.gyp` file is ready, the example addons can be configured and built using `node-gyp`: -```console -$ node-gyp configure build +```bash +node-gyp configure build ``` ### Function arguments diff --git a/doc/api/cli.md b/doc/api/cli.md index dfb29cc4e20667..47e03a29763671 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -184,8 +184,8 @@ Error: Access to this API has been restricted The process needs to have access to the `index.js` module: -```console -$ node --experimental-permission --allow-fs-read=/path/to/index.js index.js +```bash +node --experimental-permission --allow-fs-read=/path/to/index.js index.js ``` ### `--allow-fs-write` @@ -314,9 +314,9 @@ added: v10.12.0 Print source-able bash completion script for Node.js. -```console -$ node --completion-bash > node_bash_completion -$ source node_bash_completion +```bash +node --completion-bash > node_bash_completion +source node_bash_completion ``` ### `-C condition`, `--conditions=condition` @@ -339,8 +339,8 @@ The default Node.js conditions of `"node"`, `"default"`, `"import"`, and For example, to run a module with "development" resolutions: -```console -$ node -C development app.js +```bash +node -C development app.js ``` ### `--cpu-prof` @@ -1854,8 +1854,8 @@ Use `--watch-path` to specify what paths to watch. This flag cannot be combined with `--check`, `--eval`, `--interactive`, or the REPL. -```console -$ node --watch index.js +```bash +node --watch index.js ``` ### `--watch-path` @@ -1877,8 +1877,8 @@ combination with `--watch`. This flag cannot be combined with `--check`, `--eval`, `--interactive`, `--test`, or the REPL. -```console -$ node --watch-path=./src --watch-path=./tests index.js +```bash +node --watch-path=./src --watch-path=./tests index.js ``` This option is only supported on macOS and Windows. @@ -1889,8 +1889,8 @@ when the option is used on a platform that does not support it. Disable the clearing of the console when watch mode restarts the process. -```console -$ node --watch --watch-preserve-output test.js +```bash +node --watch --watch-preserve-output test.js ``` ### `--zero-fill-buffers` @@ -2525,8 +2525,8 @@ garbage collection in an effort to free unused memory. On a machine with 2 GiB of memory, consider setting this to 1536 (1.5 GiB) to leave some memory for other uses and avoid swapping. -```console -$ node --max-old-space-size=1536 index.js +```bash +node --max-old-space-size=1536 index.js ``` ### `--max-semi-space-size=SIZE` (in megabytes) diff --git a/doc/api/esm.md b/doc/api/esm.md index df50f93dddf1c9..3d450ce3c69310 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -711,7 +711,7 @@ all `import` calls. They won't apply to `require` calls; those still follow Loaders follow the pattern of `--require`: -```console +```bash node \ --experimental-loader unpkg \ --experimental-loader http-to-https \ diff --git a/doc/api/net.md b/doc/api/net.md index 4309fdb626dcc7..30aa7f6ed97456 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -1616,8 +1616,8 @@ server.listen(8124, () => { Test this by using `telnet`: -```console -$ telnet localhost 8124 +```bash +telnet localhost 8124 ``` To listen on the socket `/tmp/echo.sock`: @@ -1630,8 +1630,8 @@ server.listen('/tmp/echo.sock', () => { Use `nc` to connect to a Unix domain socket server: -```console -$ nc -U /tmp/echo.sock +```bash +nc -U /tmp/echo.sock ``` ## `net.getDefaultAutoSelectFamily()` diff --git a/doc/api/process.md b/doc/api/process.md index ad94a9721de3b7..de56638e70d27e 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -922,8 +922,8 @@ argv.forEach((val, index) => { Launching the Node.js process as: -```console -$ node process-args.js one two=three four +```bash +node process-args.js one two=three four ``` Would generate the output: @@ -1577,8 +1577,8 @@ reflected outside the Node.js process, or (unless explicitly requested) to other [`Worker`][] threads. In other words, the following example would not work: -```console -$ node -e 'process.env.foo = "bar"' && echo $foo +```bash +node -e 'process.env.foo = "bar"' && echo $foo ``` While the following will: @@ -1683,8 +1683,8 @@ include the Node.js executable, the name of the script, or any options following the script name. These options are useful in order to spawn child processes with the same execution environment as the parent. -```console -$ node --harmony script.js --version +```bash +node --harmony script.js --version ``` Results in `process.execArgv`: diff --git a/doc/api/repl.md b/doc/api/repl.md index 56828dc78670cf..16378cca8abfc2 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -712,7 +712,7 @@ terminal settings, which will allow use with `rlwrap`. For example, the following can be added to a `.bashrc` file: -```text +```bash alias node="env NODE_NO_READLINE=1 rlwrap node" ``` diff --git a/doc/api/single-executable-applications.md b/doc/api/single-executable-applications.md index fe8ff1b9545783..8642dac84f2980 100644 --- a/doc/api/single-executable-applications.md +++ b/doc/api/single-executable-applications.md @@ -26,42 +26,42 @@ Here are the steps for creating a single executable application using one such tool, [postject][]: 1. Create a JavaScript file: - ```console - $ echo 'console.log(`Hello, ${process.argv[2]}!`);' > hello.js + ```bash + echo 'console.log(`Hello, ${process.argv[2]}!`);' > hello.js ``` 2. Create a configuration file building a blob that can be injected into the single executable application (see [Generating single executable preparation blobs][] for details): - ```console - $ echo '{ "main": "hello.js", "output": "sea-prep.blob" }' > sea-config.json + ```bash + echo '{ "main": "hello.js", "output": "sea-prep.blob" }' > sea-config.json ``` 3. Generate the blob to be injected: - ```console - $ node --experimental-sea-config sea-config.json + ```bash + node --experimental-sea-config sea-config.json ``` 4. Create a copy of the `node` executable and name it according to your needs: * On systems other than Windows: - ```console - $ cp $(command -v node) hello + ```bash + cp $(command -v node) hello ``` * On Windows: Using PowerShell: - ```console - $ cp (Get-Command node).Source hello.exe + ```bash + cp (Get-Command node).Source hello.exe ``` Using Command Prompt: - ```console - $ for /F "tokens=*" %n IN ('where.exe node') DO @(copy "%n" hello.exe) + ```bash + for /F "tokens=*" %n IN ('where.exe node') DO @(copy "%n" hello.exe) ``` The `.exe` extension is necessary. @@ -70,8 +70,8 @@ tool, [postject][]: * On macOS: - ```console - $ codesign --remove-signature hello + ```bash + codesign --remove-signature hello ``` * On Windows (optional): @@ -79,8 +79,8 @@ tool, [postject][]: [signtool][] can be used from the installed [Windows SDK][]. If this step is skipped, ignore any signature-related warning from postject. - ```console - $ signtool remove /s hello.exe + ```bash + signtool remove /s hello.exe ``` 6. Inject the blob into the copied binary by running `postject` with @@ -100,20 +100,20 @@ tool, [postject][]: To summarize, here is the required command for each platform: * On Linux: - ```console - $ npx postject hello NODE_SEA_BLOB sea-prep.blob \ + ```bash + npx postject hello NODE_SEA_BLOB sea-prep.blob \ --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 ``` * On Windows: - ```console - $ npx postject hello.exe NODE_SEA_BLOB sea-prep.blob \ + ```bash + npx postject hello.exe NODE_SEA_BLOB sea-prep.blob \ --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 ``` * On macOS: - ```console - $ npx postject hello NODE_SEA_BLOB sea-prep.blob \ + ```bash + npx postject hello NODE_SEA_BLOB sea-prep.blob \ --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 \ --macho-segment-name NODE_SEA ``` @@ -122,8 +122,8 @@ tool, [postject][]: * On macOS: - ```console - $ codesign --sign - hello + ```bash + codesign --sign - hello ``` * On Windows (optional): @@ -131,8 +131,8 @@ tool, [postject][]: A certificate needs to be present for this to work. However, the unsigned binary would still be runnable. - ```console - $ signtool sign /fd SHA256 hello.exe + ```bash + signtool sign /fd SHA256 hello.exe ``` 8. Run the binary: diff --git a/doc/api/synopsis.md b/doc/api/synopsis.md index 78d17ad685bd26..26aba04f535e21 100644 --- a/doc/api/synopsis.md +++ b/doc/api/synopsis.md @@ -29,23 +29,23 @@ Now, create an empty project folder called `projects`, then navigate into it. Linux and Mac: -```console -$ mkdir ~/projects -$ cd ~/projects +```bash +mkdir ~/projects +cd ~/projects ``` Windows CMD: -```console -> mkdir %USERPROFILE%\projects -> cd %USERPROFILE%\projects +```powershell +mkdir %USERPROFILE%\projects +cd %USERPROFILE%\projects ``` Windows PowerShell: -```console -> mkdir $env:USERPROFILE\projects -> cd $env:USERPROFILE\projects +```powershell +mkdir $env:USERPROFILE\projects +cd $env:USERPROFILE\projects ``` Next, create a new source file in the `projects` @@ -73,8 +73,8 @@ server.listen(port, hostname, () => { Save the file, go back to the terminal window, and enter the following command: -```console -$ node hello-world.js +```bash +node hello-world.js ``` Output like this should appear in the terminal: diff --git a/doc/api/tls.md b/doc/api/tls.md index b0522452e7c5c0..d8e3f9c27f4811 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -285,8 +285,8 @@ failures, it is easy to not notice unnecessarily poor TLS performance. The OpenSSL CLI can be used to verify that servers are resuming sessions. Use the `-reconnect` option to `openssl s_client`, for example: -```console -$ openssl s_client -connect localhost:443 -reconnect +```bash +openssl s_client -connect localhost:443 -reconnect ``` Read through the debug output. The first connection should say "New", for diff --git a/doc/api/wasi.md b/doc/api/wasi.md index 4f84fd06b30029..f67187b7bcedb8 100644 --- a/doc/api/wasi.md +++ b/doc/api/wasi.md @@ -93,8 +93,8 @@ To run the above example, create a new WebAssembly text format file named Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm` -```console -$ wat2wasm demo.wat +```bash +wat2wasm demo.wat ``` ## Class: `WASI` diff --git a/doc/contributing/collaborator-guide.md b/doc/contributing/collaborator-guide.md index 532ecb43ca9ef5..0ad07f73144a78 100644 --- a/doc/contributing/collaborator-guide.md +++ b/doc/contributing/collaborator-guide.md @@ -555,9 +555,9 @@ this tool, please file an issue [to the issue tracker][node-core-utils-issues]. Quick example: -```text -$ npm install -g node-core-utils -$ git node land $PRID +```bash +npm install -g node-core-utils +git node land $PRID ``` To use `node-core-utils`, you will need a GitHub access token. If you do not @@ -576,37 +576,37 @@ pull request rather than rely on `git-node`. Clear any `am`/`rebase` that might already be underway: -```text -$ git am --abort -$ git rebase --abort +```bash +git am --abort +git rebase --abort ``` Checkout proper target branch: -```text -$ git checkout main +```bash +git checkout main ``` Update the tree (assumes your repository is set up as detailed in [CONTRIBUTING.md](./pull-requests.md#step-1-fork)): -```text -$ git fetch upstream -$ git merge --ff-only upstream/main +```bash +git fetch upstream +git merge --ff-only upstream/main ``` Apply external patches: -```text -$ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix +```bash +curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix ``` If the merge fails even though recent CI runs were successful, try a 3-way merge: -```text -$ git am --abort -$ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix +```bash +git am --abort +curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix ``` If the 3-way merge succeeds, check the results against the original pull @@ -617,20 +617,20 @@ has landed since the CI run. You will have to ask the author to rebase. Check and re-review the changes: -```text -$ git diff upstream/main +```bash +git diff upstream/main ``` Check the number of commits and commit messages: -```text -$ git log upstream/main...main +```bash +git log upstream/main...main ``` Squash commits and add metadata: -```text -$ git rebase -i upstream/main +```bash +git rebase -i upstream/main ``` This will open a screen like this (in the default shell editor): @@ -706,8 +706,8 @@ precaution, run tests (`make -j4 test` or `vcbuild test`). Confirm that the commit message format is correct using [core-validate-commit](https://github.com/nodejs/core-validate-commit). -```text -$ git rev-list upstream/main...HEAD | xargs core-validate-commit +```bash +git rev-list upstream/main...HEAD | xargs core-validate-commit ``` Optional: For your own commits, force push the amended commit to the pull @@ -722,8 +722,8 @@ the issue with the red closed status. Time to push it: -```text -$ git push upstream main +```bash +git push upstream main ``` Close the pull request with a "Landed in ``" comment. Even if diff --git a/doc/contributing/investigating-native-memory-leaks.md b/doc/contributing/investigating-native-memory-leaks.md index 546fbc7cf4eb50..7da7b467e9f840 100644 --- a/doc/contributing/investigating-native-memory-leaks.md +++ b/doc/contributing/investigating-native-memory-leaks.md @@ -29,7 +29,7 @@ To use Valgrind: It is an optional package in most cases and must be installed explicitly. For example on Debian/Ubuntu: -```console +```bash apt-get install valgrind ``` @@ -37,7 +37,7 @@ apt-get install valgrind The simplest invocation of Valgrind is: -```console +```bash valgrind node test.js ``` @@ -433,7 +433,7 @@ follow cover the steps needed to enable debug symbols to get more info. To enable debug symbols for all of your addons that are compiled on install use: -```console +```bash npm install --debug ``` @@ -443,7 +443,7 @@ results in the addons being compiled with the debug option. If the native addon contains pre-built binaries you will need to force a rebuild. -```console +```bash npm install --debug npm rebuild ``` @@ -517,7 +517,7 @@ To get additional information with Valgrind: * Check out the Node.js source corresponding to the release that you want to debug. For example: -```console +```bash git clone https://github.com/nodejs/node.git git checkout v12.14.1 ``` @@ -526,7 +526,7 @@ git checkout v12.14.1 [building a debug build](https://github.com/nodejs/node/blob/v12.14.1/BUILDING.md#building-a-debug-build)). For example, on \*nix: -```console +```bash ./configure --debug make -j4 ``` diff --git a/doc/contributing/maintaining/maintaining-V8.md b/doc/contributing/maintaining/maintaining-V8.md index cfd9bd6b1379b0..0fe9b393fc0f15 100644 --- a/doc/contributing/maintaining/maintaining-V8.md +++ b/doc/contributing/maintaining/maintaining-V8.md @@ -187,7 +187,7 @@ Here are the steps for the bug mentioned above: * Download and apply the commit linked-to in the issue (in this case a51f429): - ```console + ```bash curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 --directory=deps/v8 ``` diff --git a/doc/contributing/maintaining/maintaining-openssl.md b/doc/contributing/maintaining/maintaining-openssl.md index 8d640c90f38c2d..b6de7ae340ef01 100644 --- a/doc/contributing/maintaining/maintaining-openssl.md +++ b/doc/contributing/maintaining/maintaining-openssl.md @@ -61,15 +61,15 @@ release). ### OpenSSL 3.x.x -```console -% git clone https://github.com/quictls/openssl -% cd openssl -% cd ../node/deps/openssl -% rm -rf openssl -% cp -R ../../../openssl openssl -% rm -rf openssl/.git* openssl/.travis* -% git add --all openssl -% git commit openssl +```bash +git clone https://github.com/quictls/openssl +cd openssl +cd ../node/deps/openssl +rm -rf openssl +cp -R ../../../openssl openssl +rm -rf openssl/.git* openssl/.travis* +git add --all openssl +git commit openssl ``` ```text @@ -92,19 +92,19 @@ This updates all sources in deps/openssl/openssl by: Use `make` to regenerate all platform dependent files in `deps/openssl/config/archs/`: -```console +```bash # On non-Linux machines -% make gen-openssl +make gen-openssl # On Linux machines -% make -C deps/openssl/config clean -% make -C deps/openssl/config +make -C deps/openssl/config clean +make -C deps/openssl/config ``` **Note**: If the 32-bit Windows is failing to compile run this workflow instead: -```console -% make -C deps/openssl/config clean +```bash +make -C deps/openssl/config clean # Edit deps/openssl/openssl/crypto/perlasm/x86asm.pl changing # #ifdef to %ifdef to make it compatible to nasm on 32-bit Windows. # See: https://github.com/nodejs/node/pull/43603#issuecomment-1170670844 @@ -117,8 +117,8 @@ 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 +```bash +git diff -- deps/openssl ``` _Note_: On Windows, OpenSSL Configure generates a `makefile` that can be @@ -133,10 +133,10 @@ 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 -% git commit +```bash +git add deps/openssl/config/archs +git add deps/openssl/openssl +git commit ``` The commit message can be written as (with the openssl version set diff --git a/doc/contributing/pull-requests.md b/doc/contributing/pull-requests.md index 33715bc3c2096e..c35fda734f3173 100644 --- a/doc/contributing/pull-requests.md +++ b/doc/contributing/pull-requests.md @@ -70,7 +70,7 @@ it's time to create a fork. Fork the project [on GitHub](https://github.com/nodejs/node) and clone your fork locally. -```text +```bash git clone git@github.com:username/node.git cd node git remote add upstream https://github.com/nodejs/node.git @@ -79,7 +79,7 @@ git fetch upstream Configure `git` so that it knows who you are: -```text +```bash git config user.name "J. Random User" git config user.email "j.random.user@example.com" ``` @@ -99,7 +99,7 @@ As a best practice to keep your development environment as organized as possible, create local branches to work within. These should also be created directly off of the upstream default branch. -```text +```bash git checkout -b my-branch -t upstream/HEAD ``` @@ -147,7 +147,7 @@ as possible within individual commits. There is no limit to the number of commits any single pull request may have, and many contributors find it easier to review changes that are split across multiple commits. -```text +```bash git add my/changed/files git commit ``` @@ -217,7 +217,7 @@ As a best practice, once you have committed your changes, it is a good idea to use `git rebase` (not `git merge`) to synchronize your work with the main repository. -```text +```bash git fetch upstream HEAD git rebase FETCH_HEAD ``` @@ -239,7 +239,7 @@ later. Before submitting your changes in a pull request, always run the full Node.js test suite. To run the tests (including code linting) on Unix / macOS: -```text +```bash ./configure && make -j4 test ``` @@ -249,8 +249,8 @@ information, see And on Windows: -```text -> vcbuild test +```powershell +vcbuild test ``` For some configurations, running all tests might take a long time (an hour or @@ -263,7 +263,7 @@ Once you are sure your commits are ready to go, with passing tests and linting, begin the process of opening a pull request by pushing your working branch to your fork on GitHub. -```text +```bash git push origin my-branch ``` @@ -292,7 +292,7 @@ To make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request. -```text +```bash git add my/changed/files git commit git push origin my-branch @@ -301,7 +301,7 @@ git push origin my-branch If a git conflict arises, it is necessary to synchronize your branch with other changes that have landed upstream by using `git rebase`: -```text +```bash git fetch upstream HEAD git rebase FETCH_HEAD git push --force-with-lease origin my-branch diff --git a/doc/contributing/releases-node-api.md b/doc/contributing/releases-node-api.md index b5cbb321cc4b74..265c2b120e4c18 100644 --- a/doc/contributing/releases-node-api.md +++ b/doc/contributing/releases-node-api.md @@ -38,10 +38,10 @@ Node-API Working Group can be contacted best by opening up an issue on the Checkout the staging branch locally. -```console -$ git remote update -$ git checkout main -$ git reset --hard upstream/main +```bash +git remote update +git checkout main +git reset --hard upstream/main ``` If the staging branch is not up to date relative to `main`, bring the @@ -51,8 +51,8 @@ appropriate PRs and commits into it. Create a new branch named `node-api-x-proposal`, off the main branch. -```console -$ git checkout -b node-api-10-proposal upstream/main +```bash +git checkout -b node-api-10-proposal upstream/main ``` ### 3. Update `NAPI_VERSION` @@ -83,7 +83,7 @@ version, the relevant commits should already include the `NAPI_EXPERIMENTAL` define guards on the declaration of the new Node-API. Check for these guards with: -```console +```bash grep NAPI_EXPERIMENTAL src/js_native_api{_types,}.h src/node_api{_types,}.h ``` @@ -115,7 +115,7 @@ If this release includes runtime behavior version guards, the relevant commits should already include `NAPI_VERSION_EXPERIMENTAL` guard for the change. Check for these guards with: -```console +```bash grep NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc ``` @@ -127,7 +127,7 @@ If this release includes add-on tests for the new Node-APIs, the relevant commits should already include `NAPI_EXPERIMENTAL` definition for the tests. Check for these definitions with: -```console +```bash grep NAPI_EXPERIMENTAL test/node-api/*/{*.{h,c},binding.gyp} test/js-native-api/*/{*.{h,c},binding.gyp} ``` @@ -170,7 +170,7 @@ should already have documented the new behavior in a "Change History" section. For all runtime version guards updated in Step 2, check for these definitions with: -```console +```bash grep NAPI_EXPERIMENTAL doc/api/n-api.md ``` diff --git a/doc/contributing/releases.md b/doc/contributing/releases.md index b91ef8443269e4..7e3a2734684a66 100644 --- a/doc/contributing/releases.md +++ b/doc/contributing/releases.md @@ -96,14 +96,14 @@ Keyservers at are recommended. Use the [submission](https://pgp.mit.edu/) form to submit a new GPG key. You'll need to do an ASCII-armored export of your key first: -```console -$ gpg --armor --export email@server.com > ~/nodekey.asc +```bash +gpg --armor --export email@server.com > ~/nodekey.asc ``` Keys should be fetchable via: -```console -$ gpg --keyserver pool.sks-keyservers.net --recv-keys +```bash +gpg --keyserver pool.sks-keyservers.net --recv-keys ``` The key you use may be a child/subkey of an existing key. @@ -144,10 +144,10 @@ access the private repository. Checkout the staging branch locally. -```console -$ git remote update -$ git checkout v1.x-staging -$ git reset --hard upstream/v1.x-staging +```bash +git remote update +git checkout v1.x-staging +git reset --hard upstream/v1.x-staging ``` If the staging branch is not up to date relative to `main`, bring the @@ -170,8 +170,8 @@ backport PR with `Landed in ...`. Update the label on the original PR from You can add the `Backport-PR-URL` metadata by using `--backport` with `git node land` -```console -$ git node land --backport $PR-NUMBER +```bash +git node land --backport $PR-NUMBER ``` To determine the relevant commits, use @@ -184,8 +184,8 @@ duplicate or not. For a list of commits that could be landed in a patch release on v1.x: -```console -$ branch-diff v1.x-staging main --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-requested-v1.x,backport-blocked-v1.x,backport-open-v1.x,backported-to-v1.x --filter-release --format=simple +```bash +branch-diff v1.x-staging main --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-requested-v1.x,backport-blocked-v1.x,backport-open-v1.x,backported-to-v1.x --filter-release --format=simple ``` Previously released commits and version bumps do not need to be @@ -204,8 +204,8 @@ 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 from `exclude-label`.) -```console -$ branch-diff v1.x-staging main --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-requested-v1.x,backport-blocked-v1.x,backport-open-v1.x,backported-to-v1.x --filter-release --format=sha --reverse | xargs git cherry-pick +```bash +branch-diff v1.x-staging main --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-requested-v1.x,backport-blocked-v1.x,backport-open-v1.x,backported-to-v1.x --filter-release --format=sha --reverse | xargs git cherry-pick ``` When cherry-picking commits, if there are simple conflicts you can resolve @@ -216,14 +216,14 @@ Lines](https://github.com/nodejs/node/blob/HEAD/doc/contributing/backporting-to- If commits were cherry-picked in this step, check that the test still pass. -```console -$ make test +```bash +make test ``` Then, push to the staging branch to keep it up-to-date. -```console -$ git push upstream v1.x-staging +```bash +git push upstream v1.x-staging ```
@@ -234,8 +234,8 @@ GitHub organization. Add the `nodejs-private` remote: -```console -$ git remote add private git@github.com:nodejs-private/node-private.git +```bash +git remote add private git@github.com:nodejs-private/node-private.git ``` For security releases, we generally try to only include the security patches. @@ -267,8 +267,8 @@ You can integrate the PRs into the proposal without running full CI. Create a new branch named `vx.y.z-proposal`, off the corresponding staging branch. -```console -$ git checkout -b v1.2.3-proposal upstream/v1.x-staging +```bash +git checkout -b v1.2.3-proposal upstream/v1.x-staging ```
@@ -309,16 +309,16 @@ be produced with a version string that does not have a trailing pre-release tag: Collect a formatted list of commits since the last release. Use [`changelog-maker`](https://github.com/nodejs/changelog-maker) to do this: -```console -$ changelog-maker --group --markdown +```bash +changelog-maker --group --markdown ``` `changelog-maker` counts commits since the last tag and if the last tag in the repository was not on the current branch you may have to supply a `--start-ref` argument: -```console -$ changelog-maker --group --markdown --filter-release --start-ref v1.2.2 +```bash +changelog-maker --group --markdown --filter-release --start-ref v1.2.2 ``` `--filter-release` will remove the release commit from the previous release. @@ -361,8 +361,8 @@ notable. The ultimate decision rests with the releaser. You can use `branch-diff` to get a list of commits with the `notable-change` label: -```console -$ branch-diff upstream/v1.x v1.2.3-proposal --require-label=notable-change --plaintext +```bash +branch-diff upstream/v1.x v1.2.3-proposal --require-label=notable-change --plaintext ``` Be sure that the `` tag, as well as the two headings, are not indented at @@ -422,13 +422,13 @@ 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 +```bash grep REPLACEME doc/api/*.md ``` and substitute this node version with -```console +```bash sed -i "s/REPLACEME/$VERSION/g" doc/api/*.md ``` @@ -440,7 +440,7 @@ sed -i "" "s/REPLACEME/$VERSION/g" doc/api/*.md or -```console +```bash perl -pi -e "s/REPLACEME/$VERSION/g" doc/api/*.md ``` @@ -549,9 +549,9 @@ ecosystem. Use `ncu-ci` to compare `vx.x` run (10) and proposal branch (11) -```console -$ npm i -g node-core-utils -$ ncu-ci citgm 10 11 +```bash +npm i -g node-core-utils +ncu-ci citgm 10 11 ```
@@ -584,22 +584,22 @@ consider using the following approach: 1. Update staging -```console -$ git checkout v1.x-staging -$ git rebase -i $HASH_PREVIOUS_BAD_COMMIT -... drop or edit the bad commit(s) -$ git push -f upstream v1.x-staging +```bash +git checkout v1.x-staging +git rebase -i $HASH_PREVIOUS_BAD_COMMIT +# ... drop or edit the bad commit(s) +git push -f upstream v1.x-staging ``` 2. Rebase the proposal against the updated staging branch -```console -$ git checkout v1.2.3-proposal -$ git checkout -b v1.2.3-proposal-tmp -$ git checkout v1.2.3-proposal +```bash +git checkout v1.2.3-proposal +git checkout -b v1.2.3-proposal-tmp +git checkout v1.2.3-proposal -$ git reset --hard upstream/v1.x-staging -$ git cherry-pick v1.2.3-proposal-tmp +git reset --hard upstream/v1.x-staging +git cherry-pick v1.2.3-proposal-tmp ``` Note the `tmp` branch was created just to save the release commit. @@ -669,7 +669,7 @@ the build before moving forward. Use the following list as a baseline: * Run `make build-addons` before running the tests * Remove `config.gypi` file -```console +```bash ./tools/test.py --shell ~/Downloads/node-v18.5.0-linux-x64/bin/node ``` @@ -684,7 +684,7 @@ count that tag/version as lost. Tag summaries have a predictable format. Look at a recent tag to see: -```console +```bash git tag -v v6.0.0 ``` @@ -693,14 +693,14 @@ The message should look something like Install `git-secure-tag` npm module: -```console -$ npm install -g git-secure-tag +```bash +npm install -g git-secure-tag ``` Create a tag using the following command: -```console -$ git secure-tag -sm "YYYY-MM-DD Node.js vx.y.z () Release" +```bash +git secure-tag -sm "YYYY-MM-DD Node.js vx.y.z () Release" ``` The commit-sha is the release commit. You can get it easily by running `git rev-parse HEAD` @@ -738,13 +738,13 @@ version number _and_ a pre-release tag. Merge your release proposal branch into the stable branch that you are releasing from and rebase the corresponding staging branch on top of that. -```console -$ git checkout v1.x -$ git merge --ff-only v1.2.3-proposal -$ git push upstream v1.x -$ git checkout v1.x-staging -$ git rebase v1.x -$ git push upstream v1.x-staging +```bash +git checkout v1.x +git merge --ff-only v1.2.3-proposal +git push upstream v1.x +git checkout v1.x-staging +git rebase v1.x +git push upstream v1.x-staging ```
@@ -753,13 +753,13 @@ $ git push upstream v1.x-staging For security releases, you can start merging the release in the `nodejs-private` GitHub organization in advance by following the same steps: -```console -$ git checkout v1.x -$ git merge --ff-only v1.2.3-proposal -$ git push private v1.x -$ git checkout v1.x-staging -$ git rebase v1.x -$ git push private v1.x-staging +```bash +git checkout v1.x +git merge --ff-only v1.2.3-proposal +git push private v1.x +git checkout v1.x-staging +git rebase v1.x +git push private v1.x-staging ``` Once all releasers are ready, you can push each of the branches to the public @@ -769,18 +769,18 @@ repository. ### 13. Cherry-pick the release commit to `main` -```console -$ git checkout main -$ git pull upstream main -$ git cherry-pick --strategy-option=diff-algorithm=patience v1.x^ +```bash +git checkout main +git pull upstream main +git cherry-pick --strategy-option=diff-algorithm=patience v1.x^ ``` Git should stop to let you fix conflicts. Revert all changes that were made to `src/node_version.h`: -```console -$ git checkout --ours HEAD -- src/node_version.h +```bash +git checkout --ours HEAD -- src/node_version.h ```
@@ -795,8 +795,8 @@ edit it instead and: Amend the current commit to apply the changes: -```console -$ git commit --amend +```bash +git commit --amend ```
@@ -816,12 +816,12 @@ the cherry-pick step. Then finish cherry-picking and push the commit upstream: -```console -$ git add src/node_version.h doc -$ git diff --staged src doc # read output to validate that changes shows up as expected -$ git cherry-pick --continue -$ make lint-md && make lint-cpp -$ git push upstream main +```bash +git add src/node_version.h doc +git diff --staged src doc # read output to validate that changes shows up as expected +git cherry-pick --continue +make lint-md && make lint-cpp +git push upstream main ``` **Do not** cherry-pick the "Working on vx.y.z" commit to `main`. @@ -837,12 +837,12 @@ metadata. It is useful to first push the patches to `private/main` to check that the GitHub actions runs pass, before pushing to `upstream/main`: -```console -$ git checkout main -$ git reset --hard upstream/main -$ git cherry-pick ... # apply the patches which apply to main -$ git push private main # push to private main first run GitHub actions -$ git push upstream main +```bash +git checkout main +git reset --hard upstream/main +git cherry-pick ... # apply the patches which apply to main +git push private main # push to private main first run GitHub actions +git push upstream main ```
@@ -853,8 +853,8 @@ Push the tag to the repository before you promote the builds. If you haven't pushed your tag first, then build promotion won't work properly. Push the tag using the following command: -```console -$ git push upstream v1.2.3 +```bash +git push upstream v1.2.3 ``` _Note_: Please do not push the tag unless you are ready to complete the @@ -877,24 +877,24 @@ dist@direct.nodejs.org's password: The key can be loaded either with `ssh-add`: -```console +```bash # Substitute node_id_rsa with whatever you've named the key -$ ssh-add ~/.ssh/node_id_rsa +ssh-add ~/.ssh/node_id_rsa ``` or at runtime with: -```console +```bash # Substitute node_id_rsa with whatever you've named the key -$ ./tools/release.sh -i ~/.ssh/node_id_rsa +./tools/release.sh -i ~/.ssh/node_id_rsa ``` You can also specify a different ssh server address to connect to by defining a `NODEJS_RELEASE_HOST` environment variable: -```console +```bash # Substitute proxy.xyz with whatever address you intend to use -$ NODEJS_RELEASE_HOST=proxy.xyz ./tools/release.sh +NODEJS_RELEASE_HOST=proxy.xyz ./tools/release.sh ``` `tools/release.sh` will perform the following actions when run: @@ -956,8 +956,8 @@ release. However, the blog post is not yet fully automatic. Create a new blog post by running the [nodejs.org release-post.js script][]: -```console -$ node ./scripts/release-post/index.mjs x.y.z +```bash +node ./scripts/release-post/index.mjs x.y.z ``` This script will use the promoted builds and changelog to generate the post. Run @@ -1038,20 +1038,20 @@ The process of marking a release line as LTS has been automated using Start by checking out the staging branch for the release line that is going to be marked as LTS, e.g: -```console -$ git checkout v1.x-staging +```bash +git checkout v1.x-staging ``` Next, make sure you have **node-core-utils** installed: -```console -$ npm i -g node-core-utils +```bash +npm i -g node-core-utils ``` Run the prepare LTS release command: -```console -$ git node release --prepare --startLTS +```bash +git node release --prepare --startLTS ```
diff --git a/doc/contributing/writing-and-running-benchmarks.md b/doc/contributing/writing-and-running-benchmarks.md index ce1eac72a29906..eca74d4ba1c9a0 100644 --- a/doc/contributing/writing-and-running-benchmarks.md +++ b/doc/contributing/writing-and-running-benchmarks.md @@ -159,8 +159,8 @@ assert/deepequal-object.js method="notDeepEqual" strict=0 size=100 n=5000: 9,734 It is possible to execute more groups by adding extra process arguments. -```console -$ node benchmark/run.js assert async_hooks +```bash +node benchmark/run.js assert async_hooks ``` #### Filtering benchmarks @@ -263,20 +263,20 @@ First build two versions of Node.js, one from the `main` branch (here called To run multiple compiled versions in parallel you need to copy the output of the build: `cp ./out/Release/node ./node-main`. Check out the following example: -```console -$ git checkout main -$ ./configure && make -j4 -$ cp ./out/Release/node ./node-main +```bash +git checkout main +./configure && make -j4 +cp ./out/Release/node ./node-main -$ git checkout pr-5134 -$ ./configure && make -j4 -$ cp ./out/Release/node ./node-pr-5134 +git checkout pr-5134 +./configure && make -j4 +cp ./out/Release/node ./node-pr-5134 ``` The `compare.js` tool will then produce a csv file with the benchmark results. -```console -$ node benchmark/compare.js --old ./node-main --new ./node-pr-5134 string_decoder > compare-pr-5134.csv +```bash +node benchmark/compare.js --old ./node-main --new ./node-pr-5134 string_decoder > compare-pr-5134.csv ``` _Tips: there are some useful options of `benchmark/compare.js`. For example, @@ -358,8 +358,8 @@ To do this use the `scatter.js` tool, this will run a benchmark multiple times and generate a csv with the results. To see how to use this script, run `node benchmark/scatter.js`. -```console -$ node benchmark/scatter.js benchmark/string_decoder/string-decoder.js > scatter.csv +```bash +node benchmark/scatter.js benchmark/string_decoder/string-decoder.js > scatter.csv ``` After generating the csv, a comparison table can be created using the diff --git a/doc/contributing/writing-tests.md b/doc/contributing/writing-tests.md index dc4954fe9a874f..0a6af29bf04ac8 100644 --- a/doc/contributing/writing-tests.md +++ b/doc/contributing/writing-tests.md @@ -287,7 +287,7 @@ const freelist = require('node:internal/freelist'); In specific scenarios it may be useful to get a hold of `primordials` or `internalBinding()`. You can do so using -```console +```bash node --expose-internals -r internal/test/binding lib/fs.js ``` @@ -439,20 +439,20 @@ adding them to the `libraries` section in the cctest target. The test can be executed by running the `cctest` target: -```console -$ make cctest +```bash +make cctest ``` A filter can be applied to run single/multiple test cases: -```console -$ make cctest GTEST_FILTER=EnvironmentTest.AtExitWithArgument +```bash +make cctest GTEST_FILTER=EnvironmentTest.AtExitWithArgument ``` `cctest` can also be run directly which can be useful when debugging: -```console -$ out/Release/cctest --gtest_filter=EnvironmentTest.AtExit\* +```bash +out/Release/cctest --gtest_filter=EnvironmentTest.AtExit\* ``` ### Node.js test fixture diff --git a/test/wasi/README.md b/test/wasi/README.md index 87ea3fb0549cff..b99b4fa76d3993 100644 --- a/test/wasi/README.md +++ b/test/wasi/README.md @@ -4,6 +4,6 @@ Compile with clang and `wasm32-wasi` target. The clang version used must be built with wasi-libc. You can specify the location for clang and the sysroot if needed when running make: -```console -$ make CC=/usr/local/opt/llvm/bin/clang SYSROOT=/path/to/wasi-libc/sysroot +```bash +make CC=/usr/local/opt/llvm/bin/clang SYSROOT=/path/to/wasi-libc/sysroot ``` diff --git a/test/wpt/README.md b/test/wpt/README.md index d12bb71681ee1c..a378e3244a1f0b 100644 --- a/test/wpt/README.md +++ b/test/wpt/README.md @@ -34,9 +34,9 @@ See [Format of a status JSON file](#status-format) for details. Use the [git node wpt][] command to download the WPT files into `test/fixtures/wpt`. For example, to add URL tests: -```text -$ cd /path/to/node/project -$ git node wpt url +```bash +cd /path/to/node/project +git node wpt url ``` ### 3. Create the test driver @@ -71,14 +71,14 @@ with the WPT harness while taking the status file into account. Run the test using `tools/test.py` and see if there are any failures. For example, to run all the URL tests under `test/fixtures/wpt/url`: -```text -$ tools/test.py wpt/test-url +```bash +tools/test.py wpt/test-url ``` To run a specific test in WPT, for example, `url/url-searchparams.any.js`, pass the file name as argument to the corresponding test driver: -```text +```bash node test/wpt/test-url.js url-searchparams.any.js ``` @@ -149,7 +149,7 @@ expected failures. ## Format of a status JSON file -```text +```json { "something.scope.js": { // the file name // Optional: If the requirement is not met, this test will be skipped