From 0144afa76b835f95b00c316e4c42714243266a1e Mon Sep 17 00:00:00 2001
From: Evan Read <eread@gitlab.com>
Date: Wed, 5 Aug 2020 07:52:20 +0000
Subject: [PATCH] Add documentation for using overcommit
Also add example configuration for documentation linters.
---
.overcommit.yml.example | 16 ++++++++++++++++
doc/.vale/gitlab/spelling-exceptions.txt | 1 +
doc/development/contributing/style_guides.md | 19 ++++++++-----------
doc/development/documentation/index.md | 20 ++++++++++++++++++++
4 files changed, 45 insertions(+), 11 deletions(-)
diff --git a/.overcommit.yml.example b/.overcommit.yml.example
index 2cca4c0b488bb..e0f55dd4a1462 100644
--- a/.overcommit.yml.example
+++ b/.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:
diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt
index dfee30d256df9..61a45d163b507 100644
--- a/doc/.vale/gitlab/spelling-exceptions.txt
+++ b/doc/.vale/gitlab/spelling-exceptions.txt
@@ -387,6 +387,7 @@ reverify
Rubix
Rubocop
Rubular
+ruleset
runbook
runbooks
runit
diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md
index ed254052180d7..f6e64c1f1e64e 100644
--- a/doc/development/contributing/style_guides.md
+++ b/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
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index ad9ad8c64cc09..283060ba8d436 100644
--- a/doc/development/documentation/index.md
+++ b/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
--
GitLab