From 579259c578d87a3e638a5578256236c3ac3019d2 Mon Sep 17 00:00:00 2001
From: Matt Travi <programmer@travi.org>
Date: Sun, 8 Oct 2023 09:39:17 -0500
Subject: [PATCH] docs(contributing): updated details about local verification

---
 CONTRIBUTING.md | 72 ++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 54 insertions(+), 18 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 98eb4f03..e3f1e466 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -241,44 +241,80 @@ $ git clone https://github.com/semantic-release/<repo-name>
 $ cd <repo-name>
 # Assign the original repo to a remote called "upstream"
 $ git remote add upstream https://github.com/semantic-release/<repo-name>
+# Switch your node version to the version defined by the project as the development version
+# This step assumes you have already installed and configured https://github.com/nvm-sh/nvm
+# You may need to run `nvm install` if you have not already installed the development node version
+$ nvm use
 # Install the dependencies
 $ npm install
 ```
 
-### Lint
+### Verification
 
-[//]: # "TODO: rework these docs"
+The `test` script is structured to execute as much of the verification for the project as possible.
+Ensuring that the `test` script fully passes in the node version defined as the development version in the `.nvmrc`
+minimizes the chances of the test workflow failing after pushing your changes.
 
-All the [semantic-release](https://github.com/semantic-release) repositories use [XO](https://github.com/sindresorhus/xo) for linting and [Prettier](https://prettier.io) for formatting.
-Prettier formatting will be automatically verified and fixed by XO.
+> [!IMPORTANT]
+> Before pushing your code changes, be sure to run the verification for the project with `npm test`.
 
-Before pushing your code changes make sure there are no linting errors with `npm run lint`.
+[npm-run-all2](https://www.npmjs.com/package/npm-run-all2) is used to enable running multiple independent lint and test
+scripts together from the `test` script.
+This enables the test script to not only run all scripts, but also parallelize some of the scripts to optimize the overall
+time required for verification.
 
-**Tips**:
+When a failure occurs with the `test`, the output can be a bit confusing because there may be output from multiple parallel
+scripts mixed together.
+To investigate the failure with cleaner output, re-run the problematic script directly using the script name from the label
+included on the left side of the output
 
-- Most linting errors can be automatically fixed with `npm run lint -- --fix`.
-- Install the [XO plugin](https://github.com/sindresorhus/xo#editor-plugins) for your editor to see linting errors directly in your editor and automatically fix them on save.
+```shell
+$ npm run <script-name>
+```
 
-### Tests
+#### Lint
 
-[//]: # "TODO: rework these docs too"
+##### Prettier
 
-Running the integration test requires you to install [Docker](https://docs.docker.com/engine/installation) on your machine.
+All the [semantic-release](https://github.com/semantic-release) repositories use [Prettier](https://prettier.io) for formatting.
+Prettier formatting will be automatically verified by the `lint:prettier` script, included in the `test` script.
+
+> [!NOTE]
+> Most linting errors can be automatically fixed with `npm run lint:prettier:fix`.
+
+##### Other Lint Tools
+
+Other tools are used for specific compatibility concerns, but are less likely to result in failures in common contributions.
+Please follow the guidance of these tools if failures are encountered.
+
+#### Tests
+
+> [!NOTE]
+> Before pushing your code changes make sure all **tests pass** and the unit test **coverage is 100%**:
 
 All the [semantic-release](https://github.com/semantic-release) repositories use [AVA](https://github.com/avajs/ava) for writing and running tests.
 
-Before pushing your code changes make sure all **tests pass** and the **coverage is 100%**:
-
-```bash
-$ npm run test
-```
-
-**Tips:** During development you can:
+During development, you can:
 
 - run only a subset of test files with `ava <glob>`, for example `ava test/mytestfile.test.js`
 - run in watch mode with `ava -w` to automatically run a test file when you modify it
 - run only the test you are working on by adding [`.only` to the test definition](https://github.com/avajs/ava#running-specific-tests)
 
+##### Unit Tests
+
+```bash
+$ npm run test:unit
+```
+
+##### Integration Tests
+
+> [!IMPORTANT]
+> Running the integration test requires you to install [Docker](https://docs.docker.com/engine/installation) on your machine.
+
+```bash
+$ npm run test:integration
+```
+
 ### Commits
 
 [//]: # "TODO: these docs are already out of date. i'd value cleaning up the commitizen support, but w/o a special script"