Merge branch 'eread/oxford-comma-now-error' into 'master'

Improve Oxford comma check

See merge request gitlab-org/gitlab!25648

doc/.linting/vale/styles/gitlab/OxfordComma.yml

+---
+# Checks for the lack of an Oxford comma. In some cases, will catch overly
+# complex sentence structures with lots of commas.
+#
+# For a list of all options, see https://errata-ai.github.io/vale/styles/
 extends: existence
-message: Use a comma before the last "and" in a list of three or more items.
+message: Use a comma before the last "and" or "or" in a list of four or more items.
 link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation
 level: warning
-tokens:
-  - '(?:[^,]+,){1,}\s\w+\sand'
+raw:
+  - '(?:[\w-_` ]+,){2,}(?:[\w-_` ]+) (and|or)'

doc/administration/auth/authentiq.md

@@ -66,7 +66,10 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t
 
 On the sign in page there should now be an Authentiq icon below the regular sign in form. Click the icon to begin the authentication process.
 
-- If the user has the Authentiq ID app installed in their iOS or Android device, they can scan the QR code, decide what personal details to share and sign in to your GitLab installation.
+- If the user has the Authentiq ID app installed in their iOS or Android device, they can:
+  1. Scan the QR code.
+  1. Decide what personal details to share.
+  1. Sign in to your GitLab installation.
 - If not they will be prompted to download the app and then follow the procedure above.
 
 If everything goes right, the user will be returned to GitLab and will be signed in.

doc/administration/auth/ldap-ee.md

@@ -392,7 +392,7 @@ Group sync was written to be as performant as possible. Data is cached, database
 queries are optimized, and LDAP queries are minimized. The last benchmark run
 revealed the following metrics:
 
-For 20,000 LDAP users, 11,000 LDAP groups and 1,000 GitLab groups with 10
+For 20000 LDAP users, 11000 LDAP groups and 1000 GitLab groups with 10
 LDAP group links each:
 
 - Initial sync (no existing members assigned in GitLab) took 1.8 hours

doc/administration/auth/ldap.md

@@ -461,7 +461,8 @@ LDAP email address, and then sign into GitLab via their LDAP credentials.
 
 ## Enabling LDAP username lowercase
 
-Some LDAP servers, depending on their configurations, can return uppercase usernames. This can lead to several confusing issues like, for example, creating links or namespaces with uppercase names.
+Some LDAP servers, depending on their configurations, can return uppercase usernames.
+This can lead to several confusing issues such as creating links or namespaces with uppercase names.
 
 GitLab can automatically lowercase usernames provided by the LDAP server by enabling
 the configuration option `lowercase_usernames`. By default, this configuration option is `false`.

doc/administration/compliance.md

@@ -14,6 +14,6 @@ GitLab’s [security features](../security/README.md) may also help you meet rel
 |**[Lock project membership to group](../user/group/index.md#member-lock-starter)**<br>Group owners can prevent new members from being added to projects within a group.|Starter+|✓|
 |**[LDAP group sync](auth/ldap-ee.md#group-sync)**<br>GitLab Enterprise Edition gives admins the ability to automatically sync groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools.|Starter+||
 |**[LDAP group sync filters](auth/ldap-ee.md#group-sync)**<br>GitLab Enterprise Edition Premium gives more flexibility to synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions.|Premium+||
-|**[Audit logs](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives admins the ability to view any modifications made within the GitLab server in an advanced audit log system, so you can control, analyze and track every change.|Premium+||
+|**[Audit logs](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives admins the ability to view any modifications made within the GitLab server in an advanced audit log system, so you can control, analyze, and track every change.|Premium+||
 |**[Auditor users](auditor_users.md)**<br>Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance.|Premium+||
 |**[Credentials inventory](../user/admin_area/credentials_inventory.md)**<br>With a credentials inventory, GitLab administrators can keep track of the credentials used by all of the users in their GitLab instance. |Ultimate||

doc/administration/geo/disaster_recovery/background_verification.md

@@ -176,7 +176,7 @@ progress to include them in [ee-1430]. For now, you can verify their integrity
 manually by following [these instructions][foreground-verification] on both
 nodes, and comparing the output between them.
 
-In GitLab EE 12.1, Geo calculates checksums for attachments, LFS objects and
+In GitLab EE 12.1, Geo calculates checksums for attachments, LFS objects, and
 archived traces on secondary nodes after the transfer, compares it with the
 stored checksums, and rejects transfers if mismatched. Please note that Geo
 currently does not support an automatic way to verify these data if they have

doc/administration/geo/disaster_recovery/planned_failover.md

@@ -187,7 +187,7 @@ access to the **primary** node during the maintenance window.
 1. On the **secondary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues**
    and wait for all the `geo` queues to drop to 0 queued and 0 running jobs.
 1. On the **secondary** node, use [these instructions][foreground-verification]
-   to verify the integrity of CI artifacts, LFS objects and uploads in file
+   to verify the integrity of CI artifacts, LFS objects, and uploads in file
    storage.
 
 At this point, your **secondary** node will contain an up-to-date copy of everything the

doc/administration/geo/replication/datatypes.md

@@ -13,7 +13,7 @@ We currently distinguish between three different data types:
 - [Blobs](#blobs)
 - [Database](#database)
 
-See the list below of each feature or component we replicate, its corresponding data type, replication and
+See the list below of each feature or component we replicate, its corresponding data type, replication, and
 verification methods:
 
 | Type     | Feature / component                           | Replication method                          | Verification method  |

doc/administration/geo/replication/index.md

@@ -12,7 +12,8 @@ Replication with Geo is the solution for widely distributed development teams.
 
 Fetching large repositories can take a long time for teams located far from a single GitLab instance.
 
-Geo provides local, read-only instances of your GitLab instances, reducing the time it takes to clone and fetch large repositories and speeding up development.
+Geo provides local, read-only instances of your GitLab instances. This can reduce the time it takes
+to clone and fetch large repositories, speeding up development.
 
 NOTE: **Note:**
 Check the [requirements](#requirements-for-running-geo) carefully before setting up Geo.
@@ -269,7 +270,7 @@ For answers to common questions, see the [Geo FAQ](faq.md).
 
 Since GitLab 9.5, Geo stores structured log messages in a `geo.log` file. For Omnibus installations, this file is at `/var/log/gitlab/gitlab-rails/geo.log`.
 
-This file contains information about when Geo attempts to sync repositories and files. Each line in the file contains a separate JSON entry that can be ingested into Elasticsearch, Splunk, etc.
+This file contains information about when Geo attempts to sync repositories and files. Each line in the file contains a separate JSON entry that can be ingested into, for example, Elasticsearch or Splunk.
 
 For example:
 

doc/administration/git_annex.md

@@ -18,7 +18,7 @@ you can.
 
 Not being able to version control large binaries is a big problem for many
 larger organizations.
-Videos, photos, audio, compiled binaries and many other types of files are too
+Videos, photos, audio, compiled binaries, and many other types of files are too
 large. As a workaround, people keep artwork-in-progress in a Dropbox folder and
 only check in the final result. This results in using outdated files, not
 having a complete history and increases the risk of losing work.
@@ -41,13 +41,13 @@ configuration options required to enable it.
 
 `git-annex` needs to be installed both on the server and the client side.
 
-For Debian-like systems (e.g., Debian, Ubuntu) this can be achieved by running:
+For Debian-like systems (for example, Debian and Ubuntu) this can be achieved by running:
 
 ```
 sudo apt-get update && sudo apt-get install git-annex
 ```
 
-For RedHat-like systems (e.g., CentOS, RHEL) this can be achieved by running:
+For RedHat-like systems (for example, CentOS and RHEL) this can be achieved by running:
 
 ```
 sudo yum install epel-release && sudo yum install git-annex

doc/administration/incoming_email.md

@@ -81,7 +81,7 @@ incoming email domain to `hooli.com`, an attacker could abuse the "Create new
 issue by email" or
 "[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only)"
 features by using a project's unique address as the email when signing up for
-Slack, which would send a confirmation email, which would create a new issue or
+Slack. This would send a confirmation email, which would create a new issue or
 merge request on the project owned by the attacker, allowing them to click the
 confirmation link and validate their account on your company's private Slack
 instance.

doc/administration/index.md

@@ -76,7 +76,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 
 ### Maintaining GitLab
 
-- [Raketasks](../raketasks/README.md): Perform various tasks for maintenance, backups, automatic webhooks setup, etc.
+- [Raketasks](../raketasks/README.md): Perform various tasks for maintenance, backups, automatic webhooks setup, and more.
   - [Backup and restore](../raketasks/backup_restore.md): Backup and restore your GitLab instance.
 - [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Unicorn).
 - [Restart GitLab](restart_gitlab.md): Learn how to restart GitLab and its components.
@@ -107,7 +107,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Libravatar](libravatar.md): Use Libravatar instead of Gravatar for user avatars.
 - [Sign-up restrictions](../user/admin_area/settings/sign_up_restrictions.md): block email addresses of specific domains, or whitelist only specific domains.
 - [Access restrictions](../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab (SSH, HTTP, HTTPS).
-- [Authentication and Authorization](auth/README.md): Configure external authentication with LDAP, SAML, CAS and additional providers.
+- [Authentication and Authorization](auth/README.md): Configure external authentication with LDAP, SAML, CAS, and additional providers.
   - [Sync LDAP](auth/ldap-ee.md) **(STARTER ONLY)**
   - [Kerberos authentication](../integration/kerberos.md) **(STARTER ONLY)**
   - See also other [authentication](../topics/authentication/index.md#gitlab-administrators) topics (for example, enforcing 2FA).
@@ -230,4 +230,3 @@ who are aware of the risks.
   - [Strace zine](https://wizardzines.com/zines/strace/)
 - GitLab.com-specific resources:
   - [Group SAML/SCIM setup](troubleshooting/group_saml_scim.md)
-  
\ No newline at end of file

doc/administration/monitoring/performance/grafana_configuration.md

@@ -148,7 +148,14 @@ However, you should **not** reinstate your old data _except_ under one of the fo
 1. If you are certain that you changed your default admin password when you enabled Grafana
 1. If you run GitLab in a private network, accessed only by trusted users, and your Grafana login page has not been exposed to the internet
 
-If you require access to your old Grafana data but do not meet one of these criteria, you may consider reinstating it temporarily, [exporting the dashboards](https://grafana.com/docs/reference/export_import/#exporting-a-dashboard) you need, then refreshing the data and [re-importing your dashboards](https://grafana.com/docs/reference/export_import/#importing-a-dashboard). Note that this poses a temporary vulnerability while your old Grafana data is in use, and the decision to do so should be weighed carefully with your need to access existing data and dashboards.
+If you require access to your old Grafana data but do not meet one of these criteria, you may consider:
+
+1. Reinstating it temporarily.
+1. [Exporting the dashboards](https://grafana.com/docs/reference/export_import/#exporting-a-dashboard) you need.
+1. Refreshing the data and [re-importing your dashboards](https://grafana.com/docs/reference/export_import/#importing-a-dashboard).
+
+DANGER: **Danger:**
+This poses a temporary vulnerability while your old Grafana data is in use and the decision to do so should be weighed carefully with your need to access existing data and dashboards.
 
 For more information and further mitigation details, please refer to our [blog post on the security release](https://about.gitlab.com/blog/2019/08/12/critical-security-release-gitlab-12-dot-1-dot-6-released/).
 

doc/administration/restart_gitlab.md

@@ -87,8 +87,8 @@ Reconfiguring GitLab should occur in the event that something in its
 configuration (`/etc/gitlab/gitlab.rb`) has changed.
 
 When you run this command, [Chef], the underlying configuration management
-application that powers Omnibus GitLab, will make sure that all directories,
-permissions, services, etc., are in place and in the same shape that they were
+application that powers Omnibus GitLab, will make sure that all things like directories,
+permissions, and services are in place and in the same shape that they were
 initially shipped.
 
 It will also restart GitLab components where needed, if any of their
@@ -128,7 +128,7 @@ The GitLab MailRoom email processor with pid 28114 is running.
 GitLab and all its components are up and running.
 ```
 
-This should restart Unicorn, Sidekiq, GitLab Workhorse and [Mailroom][]
+This should restart Unicorn, Sidekiq, GitLab Workhorse, and [Mailroom][]
 (if enabled). The init service file that does all the magic can be found on
 your server in `/etc/init.d/gitlab`.
 
@@ -149,8 +149,8 @@ If you are using other init systems, like systemd, you can check the
 
 There is no single command to restart the entire GitLab application installed via
 the [cloud native Helm Chart](https://docs.gitlab.com/charts/). Usually, it should be
-enough to restart a specific component separately (`gitaly`, `unicorn`,
-`workhorse`, `gitlab-shell`, etc.) by deleting all the pods related to it:
+enough to restart a specific component separately (for example, `gitaly`, `unicorn`,
+`workhorse`, or `gitlab-shell`) by deleting all the pods related to it:
 
 ```shell
 kubectl delete pods -l release=<helm release name>,app=<component name>