Document linting and improve documentation linting

5 files changed, 37 insertions, 21 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 714beca89..925fc0540 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -377,7 +377,7 @@ test:macos:
     <<: *test_artifacts
 
 verify:docs:
-  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.16-vale-2.20.2-markdownlint-0.32.2-markdownlint2-0.5.1
+  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.17-vale-2.25.2-markdownlint-0.34.0-markdownlint2-0.7.1
   needs: []
   stage: analyze
   script:
diff --git a/.markdownlint.yml b/.markdownlint.yml
index 3883d544a..693520b7a 100644
--- a/.markdownlint.yml
+++ b/.markdownlint.yml
@@ -50,6 +50,7 @@ proper-names:
     "Geo",
     "Git LFS",
     "git-annex",
+    "git-credential-oauth",
     "git-sizer",
     "Git",
     "Gitaly",
@@ -100,7 +101,6 @@ proper-names:
     "OAuth",
     "OAuth 2",
     "OmniAuth",
-    "Omnibus GitLab",
     "OpenID",
     "OpenShift",
     "PgBouncer",
@@ -147,3 +147,4 @@ proper-names:
     "YouTrack"
   ]
   code_blocks: false
+  html_elements: false
diff --git a/.tool-versions b/.tool-versions
index 5e81ae83c..2deb69115 100644
--- a/.tool-versions
+++ b/.tool-versions
@@ -1,4 +1,3 @@
 # Versions of Gitaly dependencies managed by asdf.
 golang 1.20.4 1.19.9
-golangci-lint 1.50.1
 ruby 3.1.4
diff --git a/Makefile b/Makefile
index f3fabe8d1..8c358995e 100644
--- a/Makefile
+++ b/Makefile
@@ -460,9 +460,14 @@ lint-fix: ${GOLANGCI_LINT} libgit2 ${GITALY_PACKED_EXECUTABLES} ${TOOLS_DIR}/git
 	${Q}${GOLANGCI_LINT} run --fix --build-tags "${SERVER_BUILD_TAGS},${GIT2GO_BUILD_TAGS}" --out-format tab --config ${GOLANGCI_LINT_CONFIG} ${GOLANGCI_LINT_OPTIONS}
 
 .PHONY: lint-docs
-## Run Markdownlint to lint documentation.
+## Run markdownlint-cli2-config to lint the documentation.
 lint-docs:
-	${Q}markdownlint-cli2-config .markdownlint.yml README.md REVIEWING.md STYLE.md **/*.md || (echo "error: markdownlint-cli2 not found!")
+	${Q}markdownlint-cli2-config .markdownlint.yml README.md REVIEWING.md STYLE.md doc/**.md
+
+.PHONY: lint-docs-fix
+## Run markdownlint-cli2-config to lint and fix the documentation.
+lint-docs-fix:
+	${Q}markdownlint-cli2-config .markdownlint.yml README.md REVIEWING.md STYLE.md doc/**.md --fix
 
 .PHONY: lint-gitaly-linters
 ## Test Go tests in tools/golangci-lint/gitaly folder
diff --git a/doc/beginners_guide.md b/doc/beginners_guide.md
index b9dc8df02..0fbed62ca 100644
--- a/doc/beginners_guide.md
+++ b/doc/beginners_guide.md
@@ -41,30 +41,41 @@ gitaly:
 
 #### Using the Makefile
 
-Gitaly uses [Make](https://en.wikipedia.org/wiki/Make_(software)) to manage its build process, and all targets are defined in
-our top-level [Makefile](../Makefile). By default, simply running `make` will
-build our `all` target, which installs Gitaly into the `./_build/bin` directory so
-that it's easily picked up by the GDK. The following is a list of the most
-frequently used targets:
+Gitaly uses [Make](https://en.wikipedia.org/wiki/Make_(software)) to manage its build process, and all targets are
+defined in our top-level [`Makefile`](../Makefile). By default, running `make` builds the `all` target, which installs
+Gitaly into the `./_build/bin` directory so that it's picked up by GDK. The following is a list of the most frequently
+used targets:
 
 - `build`: Build Gitaly, but do not install it.
+- `install`: Build and install Gitaly. The destination directory can be modified by modifying a set of variables, most
+  importantly `PREFIX`.
+- `test`: Execute tests.
+- `clean`: Remove all generated build artifacts.
+- `help`: Print a list of available Makefile targets and variables.
 
-- `install`: Build and install Gitaly. The destination directory can be modified
-  by modifying a set of variables, most importantly `PREFIX`.
+You can modify some parts of the build process by setting up various variables. For example, by:
 
-- `test`: Execute tests.
+- Executing `make V=1`, you can do a verbose build
+- Overriding the `PROTOC_VERSION` and `PROTOC_HASH`, a different protobuf compiler version is used for generating code.
 
-- `clean`: Remove all generated build artifacts.
+If you wish to persist your configuration, create a `config.mak` file next to the Makefile and put all variables you
+wish to override in there.
 
-- `help`: Print a list of available Makefile targets and variables.
+##### Lint code and documentation
+
+The `Makefile` defines these targets for linting:
+
+- `lint`: Run [`golangci-lint`](https://golangci-lint.run) but don't correct any problems found.
+- `lint-fix`: Run `golangci-lint` and fix any problems found.
+- `lint-docs`: Run [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) in the project but don't
+  correct any problems found.
+- `lint-docs-fix`: Run `markdownlint-cli2` in the project and fix any problems found.
 
-You can modify some parts of the build process by setting up various variables.
-For example, by executing `make V=1` you can do a verbose build or by overriding
-the `PROTOC_VERSION` and `PROTOC_HASH` a different protobuf compiler version
-will be used for generating code.
+To enable linting in your code editor:
 
-If you wish to persist your configuration, you may create a `config.mak` file
-next to the Makefile and put all variables you wish to override in there.
+1. Run `make lint` at least once. That builds a version of `golangci-lint` for you.
+1. Point your code editor or code editor's plugin to the binary at `_build/tools/golangci-lint`.
+1. If necessary, add `_build/deps/libgit2/install/lib/pkgconfig` to your `PKG_CONFIG_PATH` environment variable.
 
 #### Experimenting with editing code