Merge branch 'add-lefthook-to-gemfile' into 'master'

Add Lefthook to the Gemfile and improve documentation

See merge request gitlab-org/gitlab!52106

Gemfile

@@ -336,6 +336,7 @@ end
 group :development do
   gem 'brakeman', '~> 4.2', require: false
   gem 'danger', '~> 8.0.6', require: false
+  gem 'lefthook', '~> 0.7', require: false
 
   gem 'letter_opener_web', '~> 1.3.4'
 

Gemfile.lock

@@ -658,6 +658,7 @@ GEM
       rest-client (~> 2.0)
     launchy (2.4.3)
       addressable (~> 2.3)
+    lefthook (0.7.2)
     letter_opener (1.7.0)
       launchy (~> 2.2)
     letter_opener_web (1.3.4)
@@ -1410,6 +1411,7 @@ DEPENDENCIES
   knapsack (~> 1.17)
   kramdown (~> 2.3.0)
   kubeclient (~> 4.9.1)
+  lefthook (~> 0.7)
   letter_opener_web (~> 1.3.4)
   license_finder (~> 6.0)
   licensee (~> 8.9)

doc/development/contributing/style_guides.md

@@ -15,52 +15,83 @@ settings automatically by default. If your editor/IDE does not automatically sup
 we suggest investigating to see if a plugin exists. For instance here is the
 [plugin for vim](https://github.com/editorconfig/editorconfig-vim).
 
-## Pre-push static analysis
+## Pre-push static analysis with Lefthook
 
-We strongly recommend installing [Lefthook](https://github.com/Arkweid/lefthook) to automatically check
-for static analysis offenses before pushing your changes.
+[Lefthook](https://github.com/Arkweid/lefthook) is a Git hooks manager that allows
+custom logic to be executed prior to Git committing or pushing. GitLab comes with
+Lefthook configuration (`lefthook.yml`), but it must be installed.
 
-To install `lefthook`, run the following in your GitLab source directory:
+We have a `lefthook.yml` checked in but it is ignored until Lefthook is installed.
 
-```shell
-# 1. Make sure to uninstall Overcommit first
-overcommit --uninstall
+### Uninstall Overcommit
+
+We were using Overcommit prior to Lefthook, so you may want to uninstall it first with `overcommit --uninstall`.
+
+### Install Lefthook
+
+1. Install the `lefthook` Ruby gem:
+
+   ```shell
+   bundle install
+   ```
+
+1. Install Lefthook managed Git hooks:
+
+   ```shell
+   bundle exec lefthook install
+   ```
+
+1. Test Lefthook is working by running the Lefthook `prepare-commit-msg` Git hook:
+
+   ```shell
+   bundle exec lefthook run prepare-commit-msg
+   ```
+
+This should return a fully qualified path command with no other output.
 
-# If using rbenv, at this point you may need to do: rbenv rehash
+### Lefthook configuration
 
-# 2. Install lefthook...
+The current Lefthook configuration can be found in [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml).
 
-## With Homebrew (macOS)
-brew install Arkweid/lefthook/lefthook
+Before you push your changes, Lefthook automatically runs the following checks:
 
-## Or with Go
-go get github.com/Arkweid/lefthook
+- Danger: Runs a subset of checks that `danger-review` runs on your merge requests.
+- ES lint: Run `yarn eslint` checks (with the [`.eslintrc.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.eslintrc.yml) config) on the modified `*.{js,vue}` files. Tags: `frontend`, `style`.
+- HAML lint: Run `bundle exec haml-lint` checks (with the [`.haml-lint.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.haml-lint.yml) config) on the modified `*.html.haml` files. Tags: `view`, `haml`, `style`.
+- Markdown lint: Run `yarn markdownlint` checks on the modified `*.md` files. Tags: `documentation`, `style`.
+- SCSS lint: Run `bundle exec scss-lint` checks (with the [`.scss-lint.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.scss-lint.yml) config) on the modified `*.scss{,.css}` files. Tags: `stylesheet`, `css`, `style`.
+- RuboCop: Run `bundle exec rubocop` checks (with the [`.rubocop.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.rubocop.yml) config) on the modified `*.rb` files. Tags: `backend`, `style`.
+- Vale: Run `vale` checks (with the [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) config) on the modified `*.md` files. Tags: `documentation`, `style`.
 
-## Or with Rubygems
-gem install lefthook
+In addition to the default configuration, you can define a [local configuration](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#local-config).
 
-### You may need to run the following if you're using rbenv
-rbenv rehash
+### Disable Lefthook temporarily
 
-# 3. Install the Git hooks
-lefthook install -f
+To disable Lefthook temporarily, you can set the `LEFTHOOK` environment variable to `0`. For instance:
+
+```shell
+LEFTHOOK=0 git push ...
+```
+
+### Run Lefthook hooks manually
+
+To run the `pre-push` Git hook, run:
+
+```shell
+bundle exec lefthook run pre-push
 ```
 
-Before you push your changes, Lefthook then automatically run Danger checks, and other checks
-for changed files. This saves you time as you don't have to wait for the same errors to be detected
-by CI/CD.
+For more information, check out [Lefthook documentation](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#run-githook-group-directly).
+
+### Skip Lefthook checks per tag
 
-Lefthook relies on a pre-push hook to prevent commits that violate its ruleset.
-To override this behavior, pass the environment variable `LEFTHOOK=0`. That is,
-`LEFTHOOK=0 git push`.
+To skip some checks based on tags when pushing, you can set the `LEFTHOOK_EXCLUDE` environment variable. For instance:
 
-You can also:
+```shell
+LEFTHOOK_EXCLUDE=frontend,documentation git push ...
+```
 
-- Define [local configuration](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#local-config).
-- Skip [checks per tag on the fly](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#skip-some-tags-on-the-fly).
-  For example, `LEFTHOOK_EXCLUDE=frontend git push origin`.
-- Run [hooks manually](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#run-githook-group-directly).
-  For example, `lefthook run pre-push`.
+For more information, check out [Lefthook documentation](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#skip-some-tags-on-the-fly).
 
 ## Ruby, Rails, RSpec
 

doc/development/documentation/testing.md

@@ -286,7 +286,7 @@ Configuration for `lefthook` is available in the [`lefthook.yml`](https://gitlab
 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).
+[Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis-with-lefthook).
 
 ### Show subset of Vale alerts