From a9c947efe1b99bc69b7b0c377377c116b32213f8 Mon Sep 17 00:00:00 2001
From: Evan Read <eread@gitlab.com>
Date: Thu, 8 Feb 2024 05:22:59 +0000
Subject: [PATCH] Vale and Markdown rule refresh for project

---
 .tool-versions                           |  2 +-
 doc/.vale/gitlab/HistoryItems.yml        | 13 +++++
 doc/.vale/gitlab/LatinTerms.yml          |  1 +
 doc/.vale/gitlab/Prerequisites.yml       | 14 +++++
 doc/.vale/gitlab/SubstitutionWarning.yml |  6 ++-
 doc/.vale/gitlab/Substitutions.yml       | 67 +++++++++++++-----------
 doc/.vale/gitlab/Wordy.yml               |  1 +
 doc/.vale/gitlab/spelling-exceptions.txt |  9 +++-
 gitlab-ci-config/gitlab-com.yml          | 12 +++--
 9 files changed, 86 insertions(+), 39 deletions(-)
 create mode 100644 doc/.vale/gitlab/HistoryItems.yml
 create mode 100644 doc/.vale/gitlab/Prerequisites.yml

diff --git a/.tool-versions b/.tool-versions
index 0555aaac4..eaa313545 100644
--- a/.tool-versions
+++ b/.tool-versions
@@ -1,2 +1,2 @@
 ruby 3.1.4
-vale 2.29.6
+vale 3.0.7
diff --git a/doc/.vale/gitlab/HistoryItems.yml b/doc/.vale/gitlab/HistoryItems.yml
new file mode 100644
index 000000000..72b4c1e45
--- /dev/null
+++ b/doc/.vale/gitlab/HistoryItems.yml
@@ -0,0 +1,13 @@
+---
+# Warning: gitlab.HistoryItems
+#
+# Ensures history items are properly formatted.
+#
+extends: existence
+message: "History items must always start with '> -', one item per line, even if there is only one item."
+link: https://docs.gitlab.com/ee/development/documentation/versions.html#add-a-version-history-item
+level: error
+scope: raw
+raw:
+  - '(?m)(?<=^#+[^\n]*\n\n)> [^-]|'
+  - '^> - [^\n]*\n[^\n>`]'
diff --git a/doc/.vale/gitlab/LatinTerms.yml b/doc/.vale/gitlab/LatinTerms.yml
index 0bac0448b..9fbaf278d 100644
--- a/doc/.vale/gitlab/LatinTerms.yml
+++ b/doc/.vale/gitlab/LatinTerms.yml
@@ -15,3 +15,4 @@ swap:
   e\. g\.: for example
   i\.e\.: that is
   i\. e\.: that is
+  via: "with', 'through', or 'by using"
diff --git a/doc/.vale/gitlab/Prerequisites.yml b/doc/.vale/gitlab/Prerequisites.yml
new file mode 100644
index 000000000..239f9277c
--- /dev/null
+++ b/doc/.vale/gitlab/Prerequisites.yml
@@ -0,0 +1,14 @@
+---
+# Error: gitlab.Prerequisites
+#
+# The "Prerequisites:" line should always be plural.
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: existence
+message: "Pluralize 'Prerequisites', even if it includes only one item."
+link: https://docs.gitlab.com/ee/development/documentation/topic_types/task.html#task-prerequisites
+level: warning
+nonword: true
+scope: text
+raw:
+  - '^Prerequisite:'
diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml
index c081ca5a4..8b4d3160e 100644
--- a/doc/.vale/gitlab/SubstitutionWarning.yml
+++ b/doc/.vale/gitlab/SubstitutionWarning.yml
@@ -30,12 +30,14 @@ swap:
   ex: "for example"
   file name: "filename"
   filesystem: "file system"
+  fullscreen: "full screen"
   info: "information"
   installation from source: self-compiled installation
   installations from source: self-compiled installations
   it is recommended: "you should"
   logged in user: "authenticated user"
   logged-in user: "authenticated user"
+  machine-learning: "machine learning"
   modal dialog: "dialog"
   modal window: "dialog"
   modal: "dialog"
@@ -47,6 +49,8 @@ swap:
   once that: "after that"
   once the: "after the"
   once you: "after you"
+  pack file: packfile
+  pack files: packfiles
   pop-up window: "dialog"
   pop-up: "dialog"
   popup: "dialog"
@@ -59,6 +63,6 @@ swap:
   sub-group: "subgroup"
   sub-groups: "subgroups"
   timezone: "time zone"
-  utilize: "use"
+  utiliz(?:es?|ing): "use"
   we recommend: "you should"
   within: "in"
diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml
index 10369669c..4950e495e 100644
--- a/doc/.vale/gitlab/Substitutions.yml
+++ b/doc/.vale/gitlab/Substitutions.yml
@@ -7,48 +7,35 @@
 # For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
 message: "Use '%s' instead of '%s'."
-link: https://about.gitlab.com/handbook/communication/#top-misused-terms
+link: https://handbook.gitlab.com/handbook/communication/top-misused-terms/
 level: error
 ignorecase: true
 swap:
-  codequality: code quality
-  Customer [Pp]ortal: Customers Portal
-  disallow: prevent
-  frontmatter: front matter
-  GitLabber: GitLab team member
-  GitLabbers: GitLab team members
-  GitLab-shell: GitLab Shell
-  gitlab omnibus: Linux package
-  param: parameter
-  params: parameters
-  pg: PostgreSQL
-  'postgres$': PostgreSQL
-  golang: Go
-  raketask: Rake task
-  raketasks: Rake tasks
-  rspec: RSpec
-  self hosted: self-managed
-  self-hosted: self-managed
-  styleguide: style guide
-  to login: to log in
-  can login: can log in
-  to log-in: to log in
-  can log-in: can log in
-  to signin: to sign in
-  can signin: can sign in
-  to sign-in: to sign in
-  can sign-in: can sign in
-  x509: X.509
-  yml: YAML
   admin user: administrator
   admin users: administrators
   administrator permission: administrator access
   administrator permissions: administrator access
   administrator role: administrator access
-  the administrator access level: administrator access
+  at least the Owner role: the Owner role
+  can login: can log in
+  can log-in: can log in
+  can signin: can sign in
+  can sign-in: can sign in
+  codequality: code quality
+  Customer [Pp]ortal: Customers Portal
   developer access: the Developer role
   developer permission: the Developer role
   developer permissions: the Developer role
+  disallow: prevent
+  '(?<!GitLab )Duo': GitLab Duo
+  frontmatter: front matter
+  GitLab self hosted: GitLab self-managed # https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab-self-managed
+  GitLab self-hosted: GitLab self-managed # https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab-self-managed
+  GitLabber: GitLab team member
+  GitLabbers: GitLab team members
+  GitLab-shell: GitLab Shell
+  gitlab omnibus: Linux package
+  golang: Go
   guest access: the Guest role
   guest permission: the Guest role
   guest permissions: the Guest role
@@ -58,7 +45,23 @@ swap:
   owner access: the Owner role
   owner permission: the Owner role
   owner permissions: the Owner role
+  param: parameter
+  params: parameters
+  pg: PostgreSQL
+  'postgres$': PostgreSQL
+  raketask: Rake task
+  raketasks: Rake tasks
+  rspec: RSpec
   reporter access: the Reporter role
   reporter permission: the Reporter role
   reporter permissions: the Reporter role
-  at least the Owner role: the Owner role
+  self hosted GitLab: GitLab self-managed # https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab-self-managed
+  self-hosted GitLab: GitLab self-managed # https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab-self-managed
+  styleguide: style guide
+  the administrator access level: administrator access
+  to login: to log in
+  to log-in: to log in
+  to signin: to sign in
+  to sign-in: to sign in
+  x509: X.509
+  yml: YAML
diff --git a/doc/.vale/gitlab/Wordy.yml b/doc/.vale/gitlab/Wordy.yml
index 808bedad3..9c472f665 100644
--- a/doc/.vale/gitlab/Wordy.yml
+++ b/doc/.vale/gitlab/Wordy.yml
@@ -10,6 +10,7 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.
 level: suggestion
 ignorecase: true
 swap:
+  a number of: "Specify the number or remove the phrase."
   as well as: "Use 'and' instead of 'as well as'."
   note that: "Remove the phrase 'note that'."
   please: "Use 'please' only if we've inconvenienced the user."
diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt
index 1e66d12ad..03b4ecafd 100644
--- a/doc/.vale/gitlab/spelling-exceptions.txt
+++ b/doc/.vale/gitlab/spelling-exceptions.txt
@@ -109,6 +109,7 @@ bugfixed
 bugfixes
 bugfixing
 Bugzilla
+Buildah
 Buildkite
 buildpack
 buildpacks
@@ -176,6 +177,7 @@ Codecov
 codenames
 Codepen
 CodeSandbox
+Codey
 Cognito
 Coinbase
 colocate
@@ -282,6 +284,7 @@ devfiles
 DevOps
 Dhall
 dialogs
+Diffblue
 disambiguates
 discoverability
 dismissable
@@ -350,6 +353,7 @@ Fastly
 Fastzip
 favicon
 favorited
+Fediverse
 ffaker
 Figma
 Filebeat
@@ -370,6 +374,7 @@ Flycheck
 focusable
 Forgerock
 formatters
+Fortanix
 Fortinet
 FQDNs
 FreshBooks
@@ -525,6 +530,7 @@ LaunchDarkly
 ldapsearch
 Lefthook
 Leiningen
+Lemmy
 libFuzzer
 Libgcrypt
 Libravatar
@@ -644,6 +650,7 @@ OmniAuth
 onboarding
 OpenID
 OpenShift
+OpenTelemetry
 Opsgenie
 Opstrace
 ORMs
@@ -879,7 +886,6 @@ sharded
 sharding
 SHAs
 shfmt
-Shimo
 Shippo
 Shopify
 Sidekiq
@@ -958,6 +964,7 @@ subqueried
 subqueries
 subquery
 subquerying
+Subreddit
 substring
 substrings
 subtask
diff --git a/gitlab-ci-config/gitlab-com.yml b/gitlab-ci-config/gitlab-com.yml
index 083b2a455..482c6957b 100644
--- a/gitlab-ci-config/gitlab-com.yml
+++ b/gitlab-ci-config/gitlab-com.yml
@@ -308,7 +308,7 @@ rubocop:
 
 # Perform documentation linting on Markdown files
 docs-lint markdown:
-  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.18-vale-2.29.6-markdownlint-0.37.0-markdownlint2-0.10.0
+  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.19-vale-3.0.7-markdownlint-0.39.0-markdownlint2-0.12.1
   stage: check
   cache: {}
   needs: []
@@ -325,18 +325,22 @@ docs-lint markdown:
 
 # Perform link checks on published HTML files
 docs-lint links:
-  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-html:alpine-3.18-ruby-3.2.2-08fa6df8
+  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-html:alpine-3.19-ruby-3.2.3-eee6c4c0
   stage: check
   cache: {}
   needs: []
   before_script: []
   script:
-    # Prepare docs for build
-    - mv doc/ /tmp/gitlab-docs/content/omnibus
+    # Put documentation in location expected by nanoc and configured in nanoc.yaml. For more information, see:
+    # https://gitlab.com/gitlab-org/gitlab-docs/-/blob/eee6c4c03621ff13743828ad74a8f0e8b96dfe7c/nanoc.yaml#L43
+    - mkdir /tmp/omnibus-gitlab
+    - mv doc/ /tmp/omnibus-gitlab
     - cd /tmp/gitlab-docs
     # Build HTML from Markdown
     - make compile
     # Check the internal links and anchors (in parallel)
+    # Links from the home page aren't checked because they aren't rendered here. For information, see:
+    # https://gitlab.com/gitlab-org/gitlab-docs/-/blob/eee6c4c03621ff13743828ad74a8f0e8b96dfe7c/content/index.erb#L6
     - "parallel time bundle exec nanoc check ::: internal_links internal_anchors"
   rules:
     - if: '$PIPELINE_TYPE =~ /_TEST_PIPELINE$/'