Add latest changes from gitlab-org/gitlab@master

1 files changed, 29 insertions, 0 deletions

diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md
index bb8f6a4b4a9..9facb22669b 100644
--- a/doc/development/documentation/testing.md
+++ b/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: