Merge pull request #5892 from influxdata/jts/issue5887

chore: update CONTRIBUTING.md

Author: jstirnaman

CONTRIBUTING.md

@@ -45,19 +45,22 @@ To install dependencies listed in package.json:
 3. Run `yarn` to install dependencies (including Hugo).
 4. Install the Yarn package manager and run `yarn` to install project dependencies.
 
-`package.json` contains dependencies for linting and running Git hooks.
-docs-v2 uses [Lefthook](https://github.com/evilmartians/lefthook) to configure and manage pre-commit hooks for linting and testing Markdown content.
+`package.json` contains dependencies used in `/assets/js` JavaScript code and
+dev dependencies used in pre-commit hooks for linting, syntax-checking, and testing.
 
-Other dependencies used in the project:
+Dev dependencies include:
 
-- **[prettier](https://prettier.io/docs/en/)**: formats code, including Markdown, according to style rules for consistency
+- [Lefthook](https://github.com/evilmartians/lefthook): configures and
+manages pre-commit hooks for linting and testing Markdown content.
+- [prettier](https://prettier.io/docs/en/): formats code, including Markdown, according to style rules for consistency
+- [Cypress]: e2e testing for UI elements and URLs in content
 
 ### Install Docker
 
-Install [Docker](https://docs.docker.com/get-docker/) for your system.
-
 docs-v2 includes Docker configurations (`compose.yaml` and Dockerfiles) for running the Vale style linter and tests for code blocks (Shell, Bash, and Python) in Markdown files.
 
+Install [Docker](https://docs.docker.com/get-docker/) for your system.
+
 #### Build the test dependency image
 
 After you have installed Docker, run the following command to build the test
@@ -94,7 +97,8 @@ Make your suggested changes being sure to follow the [style and formatting guide
 
 docs-v2 uses Lefthook to manage Git hooks, such as pre-commit hooks that lint Markdown and test code blocks.
 When you try to commit changes (`git commit`), Git runs
-the commands configured in `lefthook.yml` which pass your **staged** files to Vale, Prettier, and Pytest (in a Docker container).
+the commands configured in `lefthook.yml` which pass your **staged** files to Vale,
+Prettier, Cypress (for UI tests and link-checking), and Pytest (for testing Python and shell code in code blocks).
 
 ### Skip pre-commit hooks
 
@@ -113,6 +117,9 @@ LEFTHOOK=0 git commit
 
 ### Set up test scripts and credentials
 
+Tests for code blocks require your InfluxDB credentials and other typical
+InfluxDB configuration.
+
 To set up your docs-v2 instance to run tests locally, do the following:
 
 1. **Set executable permissions on test scripts** in `./test/src`:
@@ -128,91 +135,38 @@ To set up your docs-v2 instance to run tests locally, do the following:
 Cloud Dedicated instance for testing in most cases. To avoid conflicts when
      running tests, create separate Cloud Dedicated and Clustered databases.
 
-3. **Create .env.test**: Copy the `./test/env.test.example` file into each
+1. **Create .env.test**: Copy the `./test/env.test.example` file into each
     product directory to test and rename the file as `.env.test`--for example:
 
    ```sh
    ./content/influxdb/cloud-dedicated/.env.test
    ```
 
-4. Inside each product's `.env.test` file, assign your InfluxDB credentials to
-   environment variables.
+2. Inside each product's `.env.test` file, assign your InfluxDB credentials to
+   environment variables:
 
-   In addition to the usual `INFLUX_` environment variables, in your
-   `cloud-dedicated/.env.test` and `clustered/.env.test` files define the
+   - Include the usual `INFLUX_` environment variables
+   - In
+   `cloud-dedicated/.env.test` and `clustered/.env.test` files, also define the
    following variables:
 
-   - `ACCOUNT_ID`, `CLUSTER_ID`: You can find these values in your `influxctl`
-     `config.toml` configuration file.
-   - `MANAGEMENT_TOKEN`: Use the `influxctl management create` command to generate
-     a long-lived management token to authenticate Management API requests
-
-   For the full list of variables you'll need to include, see the substitution
-   patterns in `./test/src/prepare-content.sh`.
-
-   **Warning**: The database you configure in `.env.test` and any written data may
-be deleted during test runs.
+     - `ACCOUNT_ID`, `CLUSTER_ID`: You can find these values in your `influxctl`
+       `config.toml` configuration file.
+     - `MANAGEMENT_TOKEN`: Use the `influxctl management create` command to generate
+       a long-lived management token to authenticate Management API requests
 
-   **Warning**: To prevent accidentally adding credentials to the docs-v2 repo,
-Git is configured to ignore `.env*` files. Don't add your `.env.test` files to Git.
-Consider backing them up on your local machine in case of accidental deletion.
+   See the substitution
+   patterns in `./test/src/prepare-content.sh` for the full list of variables you may need to define in your `.env.test` files.
 
-5. For influxctl commands to run in tests, move or copy your `config.toml` file
+3. For influxctl commands to run in tests, move or copy your `config.toml` file
    to the `./test` directory.
 
-### Pre-commit linting and testing
-
-When you try to commit your changes using `git commit` or your editor,
-the project automatically runs pre-commit checks for spelling, punctuation,
-and style on your staged files.
-
-`.husky/pre-commit` script runs Git pre-commit hook commands, including 
-[`lint-staged`](https://github.com/lint-staged/lint-staged).
-
-The `.lintstagedrc.mjs` lint-staged configuration maps product-specific glob
-patterns to lint and test commands and passes a product-specific
-`.env.test` file to a test runner Docker container.
-The container then loads the `.env` file into the container's environment variables.
-
-To test or troubleshoot testing and linting scripts and configurations before
-committing, choose from the following:
-
-- To run pre-commit scripts without actually committing, append `exit 1` to the
-`.husky/pre-commit` script--for example:
-
-  ```sh
-  ./test/src/monitor-tests.sh start
-  npx lint-staged --relative
-  ./test/src/monitor-tests.sh kill
-  exit 1
-  ```
-
-  And then run `git commit`.
-
-  The `exit 1` status fails the commit, even if all the tasks succeed.
-
-- Use `yarn` to run one of the lint or test scripts configured in
-  `package.json`--for example:
-  
-  ```sh
-  yarn run test
-  ```
-
-- Run `lint-staged` directly and specify options:
-
-  ```sh
-  npx lint-staged --relative --verbose
-  ```
-
-The pre-commit linting configuration checks for _error-level_ problems.
-An error-level rule violation fails the commit and you must do one of the following before you can commit your changes:
-
-- fix the reported problem in the content
-
-- edit the linter rules to permanently allow the content.
-  See **Configure style rules**.
-
-- temporarily override the hook (using `git commit --no-verify`)
+> [!Warning]
+> 
+> - The database you configure in `.env.test` and any written data may
+be deleted during test runs.
+> - Don't add your `.env.test` files to Git. To prevent accidentally adding credentials to the docs-v2 repo,
+Git is configured to ignore `.env*` files. Consider backing them up on your local machine in case of accidental deletion.
 
 #### Test shell and python code blocks
 
@@ -259,7 +213,7 @@ You probably don't want to display this syntax in the docs, which unfortunately
 means you'd need to include the test block separately from the displayed code
 block.
 To hide it from users, wrap the code block inside an HTML comment.
-Pytest-codeblocks will still collect and run the code block.
+pytest-codeblocks will still collect and run the code block.
 
 ##### Mark tests to skip