From e2dcbf1c3231513c38151d729f180a54ea902da9 Mon Sep 17 00:00:00 2001 From: Nick Schonning Date: Fri, 13 Sep 2019 00:22:29 -0400 Subject: doc: use consistent unordered list style Convert to asterisks when there are mixed styles in document. Addresses Markdownlint MD004 rule PR-URL: https://github.com/nodejs/node/pull/29516 Reviewed-By: David Carlier Reviewed-By: James M Snell Reviewed-By: Trivikram Kamat --- doc/guides/contributing/pull-requests.md | 24 ++++++++++++------------ doc/guides/maintaining-the-build-files.md | 8 ++++---- doc/guides/writing-tests.md | 30 +++++++++++++++--------------- 3 files changed, 31 insertions(+), 31 deletions(-) (limited to 'doc/guides') diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md index ec6beb0bb5..a9ac6e4254 100644 --- a/doc/guides/contributing/pull-requests.md +++ b/doc/guides/contributing/pull-requests.md @@ -106,10 +106,10 @@ $ git checkout -b my-branch -t upstream/master The vast majority of Pull Requests opened against the `nodejs/node` repository includes changes to one or more of the following: -- the C/C++ code contained in the `src` directory -- the JavaScript code contained in the `lib` directory -- the documentation in `doc/api` -- tests within the `test` directory. +* the C/C++ code contained in the `src` directory +* the JavaScript code contained in the `lib` directory +* the documentation in `doc/api` +* tests within the `test` directory. If you are modifying code, please be sure to run `make lint` from time to time to ensure that the changes follow the Node.js code style guide. @@ -143,17 +143,17 @@ notes about [commit squashing](#commit-squashing). A good commit message should describe what changed and why. 1. The first line should: - - contain a short description of the change (preferably 50 characters or + * contain a short description of the change (preferably 50 characters or less, and no more than 72 characters) - - be entirely in lowercase with the exception of proper nouns, acronyms, and + * be entirely in lowercase with the exception of proper nouns, acronyms, and the words that refer to code, like function/variable names - - be prefixed with the name of the changed subsystem and start with an + * be prefixed with the name of the changed subsystem and start with an imperative verb. Check the output of `git log --oneline files/you/changed` to find out what subsystems your changes touch. Examples: - - `net: add localAddress and localPort to Socket` - - `src: fix typos in async_wrap.h` + * `net: add localAddress and localPort to Socket` + * `src: fix typos in async_wrap.h` 2. Keep the second line blank. 3. Wrap all other lines at 72 columns (except for long URLs). @@ -163,9 +163,9 @@ A good commit message should describe what changed and why. references use `Refs:`. Examples: - - `Fixes: https://github.com/nodejs/node/issues/1337` - - `Refs: https://eslint.org/docs/rules/space-in-parens.html` - - `Refs: https://github.com/nodejs/node/pull/3615` + * `Fixes: https://github.com/nodejs/node/issues/1337` + * `Refs: https://eslint.org/docs/rules/space-in-parens.html` + * `Refs: https://github.com/nodejs/node/pull/3615` 5. If your commit introduces a breaking change (`semver-major`), it should contain an explanation about the reason of the breaking change, which diff --git a/doc/guides/maintaining-the-build-files.md b/doc/guides/maintaining-the-build-files.md index d36e827145..72b2318e63 100644 --- a/doc/guides/maintaining-the-build-files.md +++ b/doc/guides/maintaining-the-build-files.md @@ -8,17 +8,17 @@ On how to build the Node.js core, see [Building Node.js](../../BUILDING.md). There are three main build files that may be directly run when building Node.js: -- `configure`: A Python 2 script that detects system capabilities and runs +* `configure`: A Python 2 script that detects system capabilities and runs [GYP][]. It generates `config.gypi` which includes parameters used by GYP to create platform-dependent build files. Its output is usually in one of these formats: Makefile, MSbuild, ninja, or XCode project files (the main Makefile mentioned below is maintained separately by humans). For a detailed guide on this script, see [configure](#configure). -- `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a +* `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a subset of the targets available in the [Makefile](#makefile), and a few targets of its own. For a detailed guide on this script, see [vcbuild.bat](#vcbuildbat). -- `Makefile`: A Makefile that can be run with GNU Make. It provides a set of +* `Makefile`: A Makefile that can be run with GNU Make. It provides a set of targets that build and test the Node.js binary, produce releases and documentation, and interact with the CI to run benchmarks or tests. For a detailed guide on this file, see [Makefile](#makefile). @@ -45,7 +45,7 @@ maintained by humans. This is not usually run on Windows, where ### Options -- `-j `: number of threads used to build the binary. On the non-CI +* `-j `: number of threads used to build the binary. On the non-CI targets, the parallel tests will take up all the available cores, regardless of this option. diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index 012532db43..f34c07cc15 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -6,17 +6,17 @@ Most tests in Node.js core are JavaScript programs that exercise a functionality provided by Node.js and check that it behaves as expected. Tests should exit with code `0` on success. A test will fail if: -- It exits by setting `process.exitCode` to a non-zero number. - - This is usually done by having an assertion throw an uncaught Error. - - Occasionally, using `process.exit(code)` may be appropriate. -- It never exits. In this case, the test runner will terminate the test because +* It exits by setting `process.exitCode` to a non-zero number. + * This is usually done by having an assertion throw an uncaught Error. + * Occasionally, using `process.exit(code)` may be appropriate. +* It never exits. In this case, the test runner will terminate the test because it sets a maximum time limit. Add tests when: -- Adding new functionality. -- Fixing regressions and bugs. -- Expanding test coverage. +* Adding new functionality. +* Fixing regressions and bugs. +* Expanding test coverage. ## Test directory structure @@ -113,14 +113,14 @@ This is the body of the test. This test is simple, it just tests that an HTTP server accepts `non-ASCII` characters in the headers of an incoming request. Interesting things to notice: -- If the test doesn't depend on a specific port number, then always use 0 +* If the test doesn't depend on a specific port number, then always use 0 instead of an arbitrary value, as it allows tests to run in parallel safely, as the operating system will assign a random port. If the test requires a specific port, for example if the test checks that assigning a specific port works as expected, then it is ok to assign a specific port number. -- The use of `common.mustCall` to check that some callbacks/listeners are +* The use of `common.mustCall` to check that some callbacks/listeners are called. -- The HTTP server closes once all the checks have run. This way, the test can +* The HTTP server closes once all the checks have run. This way, the test can exit gracefully. Remember that for a test to succeed, it must exit with a status code of 0. @@ -268,8 +268,8 @@ const freelist = require('internal/freelist'); When writing assertions, prefer the strict versions: -- `assert.strictEqual()` over `assert.equal()` -- `assert.deepStrictEqual()` over `assert.deepEqual()` +* `assert.strictEqual()` over `assert.equal()` +* `assert.deepStrictEqual()` over `assert.deepEqual()` When using `assert.throws()`, if possible, provide the full error message: @@ -318,9 +318,9 @@ features that can be used directly without a flag in [all maintained branches][]. [node.green][] lists available features in each release, such as: -- `let` and `const` over `var` -- Template literals over string concatenation -- Arrow functions when appropriate +* `let` and `const` over `var` +* Template literals over string concatenation +* Arrow functions when appropriate ## Naming Test Files -- cgit v1.2.3