diff --git a/.gitlab/merge_request_templates/Change Documentation Location.md b/.gitlab/merge_request_templates/Change Documentation Location.md index 0c675d8d0c6735d7efdea46abcff1e433ea789a1..623d15977443484ab2e90ffccd0de4f64b044d63 100644 --- a/.gitlab/merge_request_templates/Change Documentation Location.md +++ b/.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" diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index 99ad233c7e0860dcbf6020eb2dc49ebd7b72f62a..e97ae9a0c43a667139205ac24848e1955868eea5 100644 --- a/.gitlab/merge_request_templates/Documentation.md +++ b/.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 diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index b3892f8f5d9aa2b8241c9355731f7da8f4713d5b..868482148e5e5691bebe3a9825d8effc5f6ab3b6 100644 --- a/doc/administration/auth/atlassian.md +++ b/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. diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index e737e4095f1c997cfa01a0197293ce535c5aaeed..1b339b7f252c5ee4aaf2aa924544225448020604 100644 --- a/doc/development/contributing/style_guides.md +++ b/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). diff --git a/lefthook.yml b/lefthook.yml index 81ff2ecdada4204f81db2582031a77768c42859b..55027f6bf59fcd9fd318a5d59cf8611d9afaebc8 100644 --- a/lefthook.yml +++ b/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} diff --git a/scripts/lint-doc.sh b/scripts/lint-doc.sh index 33a46e73ee2d102fb49f4c1c1ce5b089f8bf6567..0b8e0010e2f1f1d02efb8158b4a96cbfe470a2bd 100755 --- a/scripts/lint-doc.sh +++ b/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 diff --git a/scripts/lint-docs-metadata.sh b/scripts/lint-docs-metadata.sh new file mode 100755 index 0000000000000000000000000000000000000000..4212adfd3f17a59fb86ff059bcb58bf276025a67 --- /dev/null +++ b/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