Merge branch 'eread/add-overcommit-docs-and-config' into 'master'

Add documentation and configuration for using overcommit

See merge request gitlab-org/gitlab!38128

.overcommit.yml.example

@@ -44,6 +44,22 @@ PreCommit:
 #    on_warn: fail # Treat all warnings as failures
   ScssLint:
     enabled: true
+  MarkdownLint:
+    enabled: true
+    description: 'Lint documentation for Markdown errors'
+    required_executable: 'node_modules/.bin/markdownlint'
+    flags: ['--config', '.markdownlint.json', 'doc/**/*.md']
+    install_command: 'yarn install'
+    include:
+      - 'doc/**/*.md'
+  Vale:
+    enabled: true
+    description: 'Lint documentation for grammatical and formatting errors'
+    required_executable: 'vale'
+    flags: ['--config', '.vale.ini', '--minAlertLevel', 'error', 'doc']
+    install_command: 'brew install vale # (or use another package manager)'
+    include:
+      - 'doc/**/*.md'
 
 CommitMsg:
   TextWidth:

doc/.vale/gitlab/spelling-exceptions.txt

@@ -387,6 +387,7 @@ reverify
 Rubix
 Rubocop
 Rubular
+ruleset
 runbook
 runbooks
 runit

doc/development/contributing/style_guides.md

@@ -10,26 +10,23 @@ we suggest investigating to see if a plugin exists. For instance here is the
 
 ## Pre-commit static analysis
 
-You're strongly advised to install
-[Overcommit](https://github.com/sds/overcommit) to automatically check for
+You should install [`overcommit`](https://github.com/sds/overcommit) to automatically check for
 static analysis offenses before committing locally.
 
-In your GitLab source directory run:
+After installing `overcommit`, run the following in your GitLab source directory:
 
 ```shell
 make -C tooling/overcommit
 ```
 
-Then before a commit is created, Overcommit will automatically check for
-RuboCop (and other checks) offenses on every modified file.
+Then before a commit is created, `overcommit` automatically checks for RuboCop (and other checks)
+offenses on every modified file.
 
-This saves you time as you don't have to wait for the same errors to be detected
-by the CI.
+This saves you time as you don't have to wait for the same errors to be detected by CI/CD.
 
-Overcommit relies on a pre-commit hook to prevent commits that violate its ruleset.
-If you wish to override this behavior, it can be done by passing the ENV variable
-`OVERCOMMIT_DISABLE`; i.e. `OVERCOMMIT_DISABLE=1 git rebase master` to rebase while
-disabling the Git hook.
+`overcommit` relies on a pre-commit hook to prevent commits that violate its ruleset. To override
+this behavior, pass the `OVERCOMMIT_DISABLE` environment variable. For example,
+`OVERCOMMIT_DISABLE=1 git rebase master` to rebase while disabling the Git hook.
 
 ## Ruby, Rails, RSpec
 

doc/development/documentation/index.md

@@ -624,6 +624,7 @@ You can use markdownlint:
 
 - [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--).
 - [Within a code editor](#configure-editors).
+- [In a `pre-commit` hook](#configure-pre-commit-hooks).
 
 #### Vale
 
@@ -650,6 +651,9 @@ You can use Vale:
 
 - [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage).
 - [Within a code editor](#configure-editors).
+- [In a `pre-commit` hook](#configure-pre-commit-hooks). Vale only reports errors in the
+  `pre-commit` hook (the same configuration as the CI/CD pipelines), and does not report suggestions
+  or warnings.
 
 #### Install linters
 
@@ -703,6 +707,22 @@ To configure Vale within your editor, install one of the following as appropriat
 
 We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application).
 
+#### Configure pre-commit hooks
+
+Git [pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) allow Git users to
+run tests or other processes before committing to a branch, with the ability to not commit to the branch if
+failures occur with these tests.
+
+[`overcommit`](https://github.com/sds/overcommit) is a Git hooks manager, making configuring,
+installing, and removing Git hooks easy.
+
+Sample configuration for `overcommit` is available in the
+[`.overcommit.yml.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.overcommit.yml.example)
+file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project.
+
+To set up `overcommit` for documentation linting, see
+[Pre-commit static analysis](../contributing/style_guides.md#pre-commit-static-analysis).
+
 #### Disable Vale tests
 
 You can disable a specific Vale linting rule or all Vale linting rules for any portion of a