diff options
Diffstat (limited to 'doc/development/documentation/testing.md')
| -rw-r--r-- | doc/development/documentation/testing.md | 73 |
1 files changed, 58 insertions, 15 deletions
diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index ab0fe7b20a9..0c65e008436 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -33,7 +33,7 @@ We also run some documentation tests in the: ## Run tests locally -Similar to [previewing your changes locally](index.md#previewing-the-changes-live), you can also +Similar to [previewing your changes locally](review_apps.md), you can also run these tests on your local computer. This has the advantage of: - Speeding up the feedback loop. You can know of any problems with the changes in your branch @@ -274,6 +274,34 @@ You can use markdownlint: - [In a code editor](#configure-editors). - [In a `pre-push` hook](#configure-pre-push-hooks). +#### Markdown rule `MD044/proper-names` (capitalization) + +A rule that can cause confusion is `MD044/proper-names`. The failure, or +how to correct it, might not be immediately clear. +This rule checks a list of known words, listed in the `.markdownlint.yml` +file in each project, to verify proper use of capitalization and backticks. +Words in backticks are ignored by markdownlint. + +In general, product names should follow the exact capitalization of the official +names of the products, protocols, and so on. + +Some examples fail if incorrect capitalization is used: + +- MinIO (needs capital `IO`) +- NGINX (needs all capitals) +- runit (needs lowercase `r`) + +Additionally, commands, parameters, values, filenames, and so on must be +included in backticks. For example: + +- "Change the `needs` keyword in your `.gitlab-ci.yml`..." + - `needs` is a parameter, and `.gitlab-ci.yml` is a file, so both need backticks. + Additionally, `.gitlab-ci.yml` without backticks fails markdownlint because it + does not have capital G or L. +- "Run `git clone` to clone a Git repository..." + - `git clone` is a command, so it must be lowercase, while Git is the product, + so it must have a capital G. + ### Vale [Vale](https://vale.sh/) is a grammar, style, and word usage linter for the @@ -395,6 +423,8 @@ In general, follow these guidelines: At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in build pipelines. +These tools can be [integrated with your code editor](#configure-editors). + #### Install markdownlint You can install either `markdownlint-cli` or `markdownlint-cli2` to run `markdownlint`. @@ -417,30 +447,43 @@ the `image:docs-lint-markdown`. #### Install Vale -To install Install [`vale`](https://github.com/errata-ai/vale/releases) for: +Install [`vale`](https://github.com/errata-ai/vale/releases) using either: -- macOS using `brew`, run: `brew install vale`. -- Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases). +- The [`asdf-vale` plugin](https://github.com/pdemagny/asdf-vale) if using [`asdf`](https://asdf-vm.com). In a checkout + of a GitLab project with a `.tool-versions` file ([example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.tool-versions)), + run: -These tools can be [integrated with your code editor](#configure-editors). + ```shell + asdf plugin add vale && asdf install vale + ``` + +- A package manager: + - macOS using `brew`, run: `brew install vale`. + - Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases). ### Update linters -It's important to use linter versions that are the same or newer than those run in -CI/CD. This provides access to new features and possible bug fixes. +It's preferable to use linter versions that are the same as those used in our CI/CD pipelines for maximum compatibility +with the linting rules we use. + +To match the versions of `markdownlint-cli` (or `markdownlint-cli2`) and `vale` used in the GitLab projects, refer to: + +- For projects managed with `asdf`, the `.tool-versions` file in the project. For example, the + [`.tool-versions` file in the `gitlab` project](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.tool-versions). +- The [versions used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) + when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. -To match the versions of `markdownlint-cli` (or `markdownlint-cli2`) and `vale` used in the GitLab projects, refer to the -[versions used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) -when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. +Versions set in these two locations should be the same. | Tool | Version | Command | Additional information | |:--------------------|:---------|:------------------------------------------|:---------------------------------------------------------------------------------------------| | `markdownlint-cli` | Latest | `yarn global add markdownlint-cli` | None. | | `markdownlint-cli2` | Latest | `yarn global add markdownlint-cli2` | None. | -| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.23.2` | The `@` indicates a specific version, and this example updates the tool to version `0.23.2`. | -| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.6.0` | The `@` indicates a specific version, and this example updates the tool to version `0.6.0`. | -| Vale | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | -| Vale | Specific | Not applicable. | Binaries can be [directly downloaded](https://github.com/errata-ai/vale/releases). | +| `markdownlint-cli` | Specific | `yarn global add markdownlint-cli@0.35.0` | The `@` indicates a specific version, and this example updates the tool to version `0.35.0`. | +| `markdownlint-cli2` | Specific | `yarn global add markdownlint-cli2@0.8.1` | The `@` indicates a specific version, and this example updates the tool to version `0.8.1`. | +| Vale (using `asdf`) | Specific | `asdf install` | Installs the version of Vale set in `.tool-versions` file in a project. | +| Vale (other) | Specific | Not applicable. | Binaries can be [directly downloaded](https://github.com/errata-ai/vale/releases). | +| Vale (using `brew`) | Latest | `brew update && brew upgrade vale` | This command is for macOS only. | ### Configure editors @@ -465,7 +508,7 @@ To configure markdownlint in your editor, install one of the following as approp To configure Vale in your editor, install one of the following as appropriate: - Sublime Text [`SublimeLinter-vale` package](https://packagecontrol.io/packages/SublimeLinter-vale). -- Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). +- Visual Studio Code [`ChrisChinchilla.vale-vscode` extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode). You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts). - Vim [ALE plugin](https://github.com/dense-analysis/ale). - JetBrains IDEs - No plugin exists, but |