Add docs metadata check to Lefthook configuration

Also share logic between Lefthook and lint-doc.sh script.

.gitlab/merge_request_templates/Change Documentation Location.md

@@ -1,6 +1,8 @@
-<!--See the general Documentation guidelines https://docs.gitlab.com/ee/development/documentation/ -->
-
-<!-- Use this description template for changing documentation location. For new docs or updates to existing docs, use the "Documentation" template -->
+<!--
+  See the general Documentation guidelines https://docs.gitlab.com/ee/development/documentation/
+  Use this description template for changing documentation location. For new documentation or
+  updates to existing documentation, use the Documentation.md template.
+-->
 
 ## What does this MR do?
 
@@ -25,4 +27,4 @@ https://docs.gitlab.com/ee/development/documentation/index.html#move-or-rename-a
 - [ ] Update the link in `features.yml` (if applicable)
 - [ ] Assign one of the technical writers for review.
 
-/label ~documentation
+/label ~documentation ~"Technical Writing"

.gitlab/merge_request_templates/Documentation.md

@@ -1,9 +1,12 @@
-<!-- Follow the documentation workflow https://docs.gitlab.com/ee/development/documentation/workflow.html -->
-<!-- Additional information is located at https://docs.gitlab.com/ee/development/documentation/ -->
-<!-- To find the designated Tech Writer for the stage/group, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers -->
+<!--
+  Follow the documentation workflow https://docs.gitlab.com/ee/development/documentation/workflow.html
+  Additional information is located at https://docs.gitlab.com/ee/development/documentation/
+  To find the designated Tech Writer for the stage/group, see
+  https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 
-<!-- Mention "documentation" or "docs" in the MR title -->
-<!-- For changing documentation location use the "Change documentation location" template -->
+  Mention "documentation" or "docs" in the MR title
+  For changing documentation location use the Change Documentation Location.md template
+-->
 
 ## What does this MR do?
 
@@ -15,11 +18,23 @@
 
 ## Author's checklist
 
-- [ ] Follow the [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/) and [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide/).
-- [ ] Ensure that the [product tier badge](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#product-tier-badges) is added to doc's `h1`.
-- [ ] [Request a review](https://docs.gitlab.com/ee/development/code_review.html#dogfooding-the-reviewers-feature) based on the documentation page's metadata and [associated Technical Writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments).
+- [ ] Follow the:
+  - [Documentation Guidelines](https://docs.gitlab.com/ee/development/documentation/).
+  - [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide/).
+- [ ] Ensure that the [product tier badge](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#product-tier-badges) is added to topic's `h1`.
+- [ ] [Request a review](https://docs.gitlab.com/ee/development/code_review.html#dogfooding-the-reviewers-feature) based on the:
+  - The documentation page's [metadata](https://docs.gitlab.com/ee/development/documentation/#metadata).
+  - The [associated Technical Writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments).
 
-To avoid having this MR be added to code verification QA issues, don't add these labels: ~"feature", ~"frontend", ~"backend", ~"bug", or ~"database"
+If you are only adding documentation, do not add any of the following labels:
+
+- `~"feature"`
+- `~"frontend"`
+- `~"backend"`
+- `~"bug"`
+- `~"database"`
+
+These labels cause the MR to be added to code verification QA issues.
 
 ## Review checklist
 

doc/administration/auth/atlassian.md

@@ -12,22 +12,14 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu
 ## Atlassian application registration
 
 1. Go to <https://developer.atlassian.com/console/myapps/> and sign-in with the Atlassian
-   account that will administer the application.
-
+   account to administer the application.
 1. Click **Create a new app**.
-
 1. Choose an App Name, such as 'GitLab', and click **Create**.
-
 1. Note the `Client ID` and `Secret` for the [GitLab configuration](#gitlab-configuration) steps.
-
 1. In the left sidebar under **APIS AND FEATURES**, click **OAuth 2.0 (3LO)**.
-
 1. Enter the GitLab callback URL using the format `https://gitlab.example.com/users/auth/atlassian_oauth2/callback` and click **Save changes**.
-
 1. Click **+ Add** in the left sidebar under **APIS AND FEATURES**.
-
 1. Click **Add** for **Jira platform REST API** and then **Configure**.
-
 1. Click **Add** next to the following scopes:
     - **View Jira issue data**
     - **View user profiles**
@@ -50,7 +42,6 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu
    ```
 
 1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add `atlassian_oauth2` as an OAuth provider.
-
 1. Add the provider configuration for Atlassian:
 
    For Omnibus GitLab installations:
@@ -76,9 +67,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu
    ```
 
 1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in [application registration](#atlassian-application-registration) steps.
-
 1. Save the configuration file.
-
 1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
 
 On the sign-in page there should now be an Atlassian icon below the regular sign in form. Click the icon to begin the authentication process.

doc/development/contributing/style_guides.md

@@ -62,6 +62,7 @@ Before you push your changes, Lefthook automatically runs the following checks:
 - SCSS lint: Run `yarn lint:stylelint` checks (with the [`.stylelintrc`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.stylelintrc) configuration) 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) configuration) 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) configuration) on the modified `*.md` files. Tags: `documentation`, `style`.
+- Documentation metadata: Run checks for the absence of [documentation metadata](../documentation/index.md#metadata).
 
 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).
 

lefthook.yml

@@ -39,8 +39,13 @@ pre-push:
       glob: 'doc/*.md'
       run: if command -v vale 2> /dev/null; then vale --config .vale.ini --minAlertLevel error {files}; else echo "Vale not found. Install Vale"; fi
     gettext:
-      skip: true # This is disabled by default. You can enable this check by adding skip: false in lefhook-local.yml https://github.com/evilmartians/lefthook/blob/master/docs/full_guide.md#skipping-commands
+      skip: true  # This is disabled by default. You can enable this check by adding skip: false in lefhook-local.yml https://github.com/evilmartians/lefthook/blob/master/docs/full_guide.md#skipping-commands
       tags: backend frontend view haml
       files: git diff --name-only --diff-filter=d $(git merge-base origin/master HEAD)..HEAD | while read file;do git diff --unified=1 $(git merge-base origin/master HEAD)..HEAD $file | grep -Fqe '_(' && echo $file;done; true
       glob: "*.{haml,rb,js,vue}"
       run: bin/rake gettext:updated_check
+    docs-metadata:  # See https://docs.gitlab.com/ee/development/documentation/#metadata
+      tags: documentation style
+      files: git diff --name-only --diff-filter=d $(git merge-base origin/master HEAD)..HEAD
+      glob: 'doc/*.md'
+      run: scripts/lint-docs-metadata.sh {files}

scripts/lint-doc.sh

@@ -21,11 +21,9 @@ fi
 # Documentation pages need front matter for tracking purposes.
 echo '=> Checking documentation for front matter...'
 echo
-no_frontmatter=$(find doc -name "*.md" -exec head -n1 {} \; | grep -v  --count -- ---)
-if [ $no_frontmatter -ne 0 ]
+if ! scripts/lint-docs-metadata.sh
 then
   echo '✖ ERROR: These documentation pages need front matter. See https://docs.gitlab.com/ee/development/documentation/index.html#stage-and-group-metadata for how to add it.' >&2
-  find doc -name "*.md" -exec sh -c 'if (head -n 1 "{}" | grep -v -- --- >/dev/null); then echo "{}"; fi' \; 2>&1
   echo
   ((ERRORCODE++))
 fi

scripts/lint-docs-metadata.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+
+COLOR_RED="\e[31m"
+COLOR_GREEN="\e[32m"
+COLOR_RESET="\e[39m"
+VERBOSE=false
+CHECK_ALL=true
+
+FAILING_FILES=0
+TOTAL_FILES=0
+
+# Parse arguments
+for arg in "$@"; do
+  case $arg in
+
+  --verbose)
+    VERBOSE=true
+    ;;
+  --help | -h)
+    cat <<EOF
+usage: lint-docs-metadata.sh [--help][--verbose] <file...>
+
+If no files are provided, all markdown files in doc/ are checked.
+EOF
+    exit 0
+    ;;
+  *)
+    CHECK_ALL=false
+    ;;
+
+  esac
+done
+
+function check_file {
+  local file
+  file="$1"
+  TOTAL_FILES=$((TOTAL_FILES + 1))
+  if [ "$(head -n1 "$file")" != "---" ]; then
+    printf "${COLOR_RED}Documentation metadata missing in %s.${COLOR_RESET}\n" "$file" >&2
+    FAILING_FILES=$((FAILING_FILES + 1))
+  elif [ "$VERBOSE" == "true" ]; then
+    printf "Documentation metadata found in %s.\n" "$file"
+  fi
+}
+
+function check_all_files {
+  while IFS= read -r -d '' file; do
+    check_file "$file"
+  done < <(find "doc" -name "*.md" -type f -print0)
+}
+
+if [[ "$CHECK_ALL" = "true" ]]; then
+  # shellcheck disable=SC2059
+  printf "No files supplied. Checking all markdown files in doc/.\n"
+  check_all_files
+else
+  # Takes a list of Markdown files as a parameter
+  for file in "$@"; do
+    # Skipping parameters
+    [[ $file = --* ]] && continue
+    check_file "$file"
+  done
+fi
+
+if [ "$FAILING_FILES" -gt 0 ]; then
+  # shellcheck disable=SC2059
+  printf "\n${COLOR_RED}Documentation metadata is missing in ${FAILING_FILES} of ${TOTAL_FILES} documentation files.${COLOR_RESET} For more information, see https://docs.gitlab.com/ee/development/documentation/#metadata.\n" >&2
+  exit 1
+else
+  # shellcheck disable=SC2059
+  printf "${COLOR_GREEN}Documentation metadata found in ${TOTAL_FILES} documentation files.${COLOR_RESET}\n"
+  exit 0
+fi