Add Vale warnings to Lefthook configuration

doc/ci/unit_test_reports.md

@@ -77,7 +77,7 @@ If a test failed in the project's default branch in the last 14 days, a message
 
 To enable the Unit test reports in merge requests, you must add
 [`artifacts:reports:junit`](yaml/artifacts_reports.md#artifactsreportsjunit)
-in `.gitlab-ci.yml`, and specify the path(s) of the generated test reports.
+in `.gitlab-ci.yml`, and specify the paths of the generated test reports.
 The reports must be `.xml` files, otherwise [GitLab returns an Error 500](https://gitlab.com/gitlab-org/gitlab/-/issues/216575).
 
 In the following examples, the job in the `test` stage runs and GitLab

doc/development/documentation/testing.md

@@ -365,6 +365,35 @@ file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project.
 To set up `lefthook` for documentation linting, see
 [Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis-with-lefthook).
 
+#### Show Vale warnings on push
+
+By default, `lefthook` shows only Vale errors when pushing changes to a branch. The default branches
+have no Vale errors, so any errors listed here are introduced by commits to the branch.
+
+To also see the Vale warnings when pushing to a branch, set a local environment variable: `VALE_WARNINGS=true`.
+
+Enable Vale warnings on push to improve the documentation suite by:
+
+- Detecting warnings you might be introducing with your commits.
+- Identifying warnings that already exist in the page, which you can resolve to reduce technical debt.
+
+These warnings:
+
+- Don't stop the push from working.
+- Don't result in a broken pipeline.
+- Include all warnings for a file, not just warnings that are introduced by the commits.
+
+To enable Vale warnings on push:
+
+- Automatically, add `VALE_WARNINGS=true` to your shell configuration.
+- Manually, prepend `VALE_WARNINGS=true` to invocations of `lefthook`. For example:
+
+  ```shell
+  VALE_WARNINGS=true bundle exec lefthook run pre-push
+  ```
+
+You can also [configure your editor](#configure-editors) to show Vale warnings.
+
 ### Show subset of Vale alerts
 
 You can set Visual Studio Code to display only a subset of Vale alerts when viewing files:

lefthook.yml

@@ -42,7 +42,7 @@ pre-push:
       tags: documentation style
       files: git diff --name-only --diff-filter=d $(git merge-base origin/master HEAD)..HEAD
       glob: 'doc/*.md'
-      run: 'if command -v vale > /dev/null 2>&1; then if ! vale --config .vale.ini --minAlertLevel error {files}; then echo "ERROR: Fix any linting errors and make sure you are using the latest version of Vale."; exit 1; fi; else echo "ERROR: Vale not found. For more information, see https://docs.errata.ai/vale/install."; exit 1; fi'
+      run: 'if [ $VALE_WARNINGS ]; then minWarnings=warning; else minWarnings=error; fi; if command -v vale > /dev/null 2>&1; then if ! vale --config .vale.ini --minAlertLevel $minWarnings {files}; then echo "ERROR: Fix any linting errors and make sure you are using the latest version of Vale."; exit 1; fi; else echo "ERROR: Vale not found. For more information, see https://docs.errata.ai/vale/install."; exit 1; fi'
     gettext:
       skip: true  # This is disabled by default. You can enable this check by adding skip: false in lefhook-local.yml https://github.com/evilmartians/lefthook/blob/master/docs/full_guide.md#skipping-commands
       tags: backend frontend view haml