Merge branch 'eread/fix-lack-of-oxford-comma' into 'master'

Fix lack of Oxford comma in some documentation

See merge request gitlab-org/gitlab!26039

doc/api/repository_files.md

@@ -2,7 +2,7 @@
 
 **CRUD for repository files**
 
-**Create, read, update and delete repository files using this API**
+**Create, read, update, and delete repository files using this API**
 
 The different scopes available using [personal access tokens](../user/profile/personal_access_tokens.md) are depicted
 in the following table.
@@ -242,7 +242,7 @@ If the commit fails for any reason we return a 400 error with a non-specific
 error message. Possible causes for a failed commit include:
 
 - the `file_path` contained `/../` (attempted directory traversal);
-- the new file contents were identical to the current file contents, i.e. the
+- the new file contents were identical to the current file contents. That is, the
   user tried to make an empty commit;
 - the branch was updated by a Git push while the file edit was in progress.
 

doc/api/resource_label_events.md

 # Resource label events API
 
-Resource label events keep track about who, when, and which label was added or removed to an issuable.
+Resource label events keep track about who, when, and which label was added to, or removed from, an issuable.
 
 ## Issues
 

doc/api/services.md

@@ -567,7 +567,7 @@ Set Hangouts Chat service for a project.
 PUT /projects/:id/services/hangouts-chat
 ```
 
->**Note:** Specific event parameters (e.g. `push_events` flag) were [introduced in v10.4][11435]
+>**Note:** Specific event parameters (for example, `push_events` flag) were [introduced in v10.4][11435]
 
 Parameters:
 
@@ -833,7 +833,7 @@ DELETE /projects/:id/services/mattermost-slash-commands
 
 ## Packagist
 
-Update your project on Packagist, the main Composer repository, when commits or tags are pushed to GitLab.
+Update your project on Packagist (the main Composer repository) when commits or tags are pushed to GitLab.
 
 ### Create/Edit Packagist service
 
@@ -1068,7 +1068,7 @@ Set Slack service for a project.
 PUT /projects/:id/services/slack
 ```
 
->**Note:** Specific event parameters (e.g. `push_events` flag and `push_channel`) were [introduced in v10.4][11435]
+>**Note:** Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4][11435]
 
 Parameters:
 
@@ -1177,7 +1177,7 @@ Set Mattermost service for a project.
 PUT /projects/:id/services/mattermost
 ```
 
->**Note:** Specific event parameters (e.g. `push_events` flag and `push_channel`) were [introduced in v10.4][11435]
+>**Note:** Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4][11435]
 
 Parameters:
 

doc/api/settings.md

@@ -201,7 +201,7 @@ are listed in the descriptions of the relevant settings.
 | `commit_email_hostname`                  | string           | no                                   | Custom hostname (for private commit emails). |
 | `container_registry_token_expire_delay`  | integer          | no                                   | Container Registry token duration in minutes. |
 | `default_artifacts_expire_in`            | string           | no                                   | Set the default expiration time for each job's artifacts. |
-| `default_branch_protection`              | integer          | no                                   | Determine if developers can push to master. Can take: `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push or delete the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. |
+| `default_branch_protection`              | integer          | no                                   | Determine if developers can push to master. Can take: `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push, or delete, the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. |
 | `default_ci_config_path`                 | string           | no                                   | Default CI configuration path for new projects (`.gitlab-ci.yml` if not set). |
 | `default_group_visibility`               | string           | no                                   | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. |
 | `default_project_creation`               | integer          | no                                   | Default project creation protection. Can take: `0` _(No one)_, `1` _(Maintainers)_ or `2` _(Developers + Maintainers)_|
@@ -230,7 +230,7 @@ are listed in the descriptions of the relevant settings.
 | `elasticsearch_namespace_ids`            | array of integers | no                                  | **(PREMIUM)** The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. |
 | `elasticsearch_project_ids`              | array of integers | no                                  | **(PREMIUM)** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. |
 | `elasticsearch_search`                   | boolean          | no                                   | **(PREMIUM)** Enable Elasticsearch search |
-| `elasticsearch_url`                      | string           | no                                   | **(PREMIUM)** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (e.g., `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). |
+| `elasticsearch_url`                      | string           | no                                   | **(PREMIUM)** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (for example, `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (for example, `http://<username>:<password>@<elastic_host>:9200/`). |
 | `email_additional_text`                  | string           | no                                   | **(PREMIUM)** Additional text added to the bottom of every email for legal/auditing/compliance reasons |
 | `email_author_in_body`                   | boolean          | no                                   | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. |
 | `enabled_git_access_protocol`            | string           | no                                   | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. |
@@ -323,23 +323,23 @@ are listed in the descriptions of the relevant settings.
 | `slack_app_id`                           | string           | required by: `slack_app_enabled`      | **(PREMIUM)** The app id of the Slack-app. |
 | `slack_app_secret`                       | string           | required by: `slack_app_enabled`      | **(PREMIUM)** The app secret of the Slack-app. |
 | `slack_app_verification_token`           | string           | required by: `slack_app_enabled`      | **(PREMIUM)** The verification token of the Slack-app. |
-| `snowplow_collector_hostname`            | string           | required by: `snowplow_enabled`      | The Snowplow collector hostname. (e.g. `snowplow.trx.gitlab.net`) |
-| `snowplow_cookie_domain`                 | string           | no                                   | The Snowplow cookie domain. (e.g. `.gitlab.com`) |
+| `snowplow_collector_hostname`            | string           | required by: `snowplow_enabled`      | The Snowplow collector hostname. (for example, `snowplow.trx.gitlab.net`) |
+| `snowplow_cookie_domain`                 | string           | no                                   | The Snowplow cookie domain. (for example, `.gitlab.com`) |
 | `snowplow_enabled`                       | boolean          | no                                   | Enable snowplow tracking. |
-| `snowplow_app_id`                        | string           | no                                   | The Snowplow site name / application id. (e.g. `gitlab`) |
+| `snowplow_app_id`                        | string           | no                                   | The Snowplow site name / application id. (for example, `gitlab`) |
 | `snowplow_iglu_registry_url`             | string           | no                                   | The Snowplow base Iglu Schema Registry URL to use for custom context and self describing events'|
 | `sourcegraph_enabled`                    | boolean          | no                                    | Enables Sourcegraph integration. Default is `false`. **If enabled, requires** `sourcegraph_url`. |
 | `sourcegraph_url`                        | string           | required by: `sourcegraph_enabled`    | The Sourcegraph instance URL for integration. |
 | `sourcegraph_public_only`                | boolean          | no                                   | Blocks Sourcegraph from being loaded on private and internal projects. Default is `true`. |
 | `terminal_max_session_time`              | integer          | no                                   | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. |
 | `terms`                                  | text             | required by: `enforce_terms`         | (**Required by:** `enforce_terms`) Markdown content for the ToS. |
-| `throttle_authenticated_api_enabled`     | boolean          | no                                   | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). |
+| `throttle_authenticated_api_enabled`     | boolean          | no                                   | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). |
 | `throttle_authenticated_api_period_in_seconds` | integer    | required by: `throttle_authenticated_api_enabled` | Rate limit period in seconds.  |
 | `throttle_authenticated_api_requests_per_period` | integer  | required by: `throttle_authenticated_api_enabled` | Max requests per period per user. |
-| `throttle_authenticated_web_enabled`     | boolean          | no                                   | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). |
+| `throttle_authenticated_web_enabled`     | boolean          | no                                   | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). |
 | `throttle_authenticated_web_period_in_seconds` | integer    | required by: `throttle_authenticated_web_enabled` | Rate limit period in seconds. |
 | `throttle_authenticated_web_requests_per_period` | integer  | required by: `throttle_authenticated_web_enabled` | Max requests per period per user. |
-| `throttle_unauthenticated_enabled`       | boolean          | no                                   | (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). |
+| `throttle_unauthenticated_enabled`       | boolean          | no                                   | (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). |
 | `throttle_unauthenticated_period_in_seconds` | integer      | required by: `throttle_unauthenticated_enabled` | Rate limit period in seconds.  |
 | `throttle_unauthenticated_requests_per_period` | integer    | required by: `throttle_unauthenticated_enabled` | Max requests per period per IP. |
 | `time_tracking_limit_to_hours`           | boolean          | no                                   | Limit display of time tracking units to hours. Default is `false`. |

doc/api/users.md

@@ -435,8 +435,8 @@ Parameters:
 
 On password update, user will be forced to change it upon next login.
 Note, at the moment this method does only return a `404` error,
-even in cases where a `409` (Conflict) would be more appropriate,
-e.g. when renaming the email address to some existing one.
+even in cases where a `409` (Conflict) would be more appropriate.
+For example, when renaming the email address to some existing one.
 
 ## Delete authentication identity from user
 
@@ -1389,7 +1389,7 @@ The activities that update the timestamp are:
 
 - Git HTTP/SSH activities (such as clone, push)
 - User logging in into GitLab
-- User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/54947) in GitLab 11.8)
+- User visiting pages related to Dashboards, Projects, Issues, and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/54947) in GitLab 11.8)
 - User using the API
 
 By default, it shows the activity for all users in the last 6 months, but this can be
@@ -1403,7 +1403,7 @@ Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `from` | string | no | Date string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`. Defaults to 6 months ago. |
+| `from` | string | no | Date string in the format YEAR-MONTH-DAY. For example, `2016-03-11`. Defaults to 6 months ago. |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/activities

doc/ci/docker/using_docker_images.md

@@ -12,7 +12,7 @@ run applications in independent "containers" that are run within a single Linux
 instance. [Docker Hub][hub] has a rich database of pre-built images that can be
 used to test and build your applications.
 
-Docker, when used with GitLab CI, runs each job in a separate and isolated
+When used with GitLab CI, Docker runs each job in a separate and isolated
 container using the predefined image that is set up in
 [`.gitlab-ci.yml`](../yaml/README.md).
 
@@ -588,7 +588,7 @@ There are two ways to determine the value of `DOCKER_AUTH_CONFIG`:
   # Example output to copy
   bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
   ```
-  
+
   Create the Docker JSON configuration content as follows:
 
   ```json

doc/ci/environments.md

@@ -118,7 +118,7 @@ NOTE: **Note:**
 The `environment` keyword defines where the app is deployed.
 The environment `name` and `url` is exposed in various places
 within GitLab. Each time a job that has an environment specified
-succeeds, a deployment is recorded, along with the Git SHA and environment name.
+succeeds, a deployment is recorded, along with the Git SHA, and environment name.
 
 CAUTION: **Caution**:
 Some characters are not allowed in environment names. Use only letters,

doc/ci/examples/deployment/composer-npm-deploy.md

@@ -44,7 +44,7 @@ All these operations will put all files into a `build` folder, which is ready to
 
 ## How to transfer files to a live server
 
-You have multiple options: rsync, scp, sftp and so on. For now, we will use scp.
+You have multiple options: rsync, scp, sftp, and so on. For now, we will use scp.
 
 To make this work, you need to add a GitLab CI/CD Variable (accessible on `gitlab.example/your-project-name/variables`). That variable will be called `STAGING_PRIVATE_KEY` and it's the  **private** SSH key of your server.
 

doc/ci/examples/laravel_with_gitlab_and_envoy/index.md

@@ -22,7 +22,7 @@ and you know how to use GitLab.
 
 Laravel is a high quality web framework written in PHP.
 It has a great community with a [fantastic documentation](https://laravel.com/docs).
-Aside from the usual routing, controllers, requests, responses, views, and (blade) templates, out of the box Laravel provides plenty of additional services such as cache, events, localization, authentication and many others.
+Aside from the usual routing, controllers, requests, responses, views, and (blade) templates, out of the box Laravel provides plenty of additional services such as cache, events, localization, authentication, and many others.
 
 We will use [Envoy](https://laravel.com/docs/master/envoy) as an SSH task runner based on PHP.
 It uses a clean, minimal [Blade syntax](https://laravel.com/docs/master/blade) to set up tasks that can run on remote servers, such as, cloning your project from the repository, installing the Composer dependencies, and running [Artisan commands](https://laravel.com/docs/master/artisan).
@@ -82,7 +82,7 @@ git push -u origin master
 ## Configure the production server
 
 Before we begin setting up Envoy and GitLab CI/CD, let's quickly make sure the production server is ready for deployment.
-We have installed LEMP stack which stands for Linux, NGINX, MySQL and PHP on our Ubuntu 16.04.
+We have installed LEMP stack which stands for Linux, NGINX, MySQL, and PHP on our Ubuntu 16.04.
 
 ### Create a new user
 
@@ -194,7 +194,7 @@ To start, we create an `Envoy.blade.php` in the root of our app with a simple ta
 @endtask
 ```
 
-As you may expect, we have an array within `@servers` directive at the top of the file, which contains a key named `web` with a value of the server's address (e.g. `deployer@192.168.1.1`).
+As you may expect, we have an array within `@servers` directive at the top of the file, which contains a key named `web` with a value of the server's address (for example, `deployer@192.168.1.1`).
 Then within our `@task` directive we define the bash commands that should be run on the server when the task is executed.
 
 On the local machine use the `run` command to run Envoy tasks.

doc/ci/large_repositories/index.md

@@ -104,7 +104,7 @@ and that your repository is clean.
 [`GIT_CLEAN_FLAGS`](../yaml/README.md#git-clean-flags) is disabled when set
 to `none`. On very big repositories, this might be desired because `git
 clean` is disk I/O intensive. Controlling that with `GIT_CLEAN_FLAGS: -ffdx
--e .build/`, for example, allows you to control and disable removal of some
+-e .build/` (for example) allows you to control and disable removal of some
 directories within the worktree between subsequent runs, which can speed-up
 the incremental builds. This has the biggest effect if you re-use existing
 machines and have an existing worktree that you can re-use for builds.

doc/ci/merge_request_pipelines/index.md

@@ -89,7 +89,7 @@ Read the [documentation on Merge Trains](pipelines_for_merged_results/merge_trai
 The behavior of the `only: [merge_requests]` parameter is such that _only_ jobs with
 that parameter are run in the context of a merge request; no other jobs will be run.
 
-However, you may want to reverse this behavior, having all of your jobs to run _except_
+However, you can invert this behavior and have all of your jobs run _except_
 for one or two.
 
 Consider the following pipeline, with jobs `A`, `B`, and `C`. Imagine you want:

doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md

@@ -111,7 +111,7 @@ To check and set these feature flag values, please ask an administrator to:
 
 Since pipelines for merged results are a run on a merge ref of a merge request
 (`refs/merge-requests/<iid>/merge`), the Git reference could be overwritten at an
-unexpected timing, for example, when a source or target branch is advanced.
+unexpected timing. For example, when a source or target branch is advanced.
 In this case, the pipeline fails because of `fatal: reference is not a tree:` error,
 which indicates that the checkout-SHA is not found in the merge ref.
 

doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md

@@ -21,7 +21,7 @@ just as it works in the current state. However, instead of queuing and waiting,
 each item takes the completed state of the previous (pending) merge ref, adds its own changes,
 and starts the pipeline immediately in parallel under the assumption that everything is going to pass.
 
-In this way, if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying.
+This means that if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying.
 If the button is subsequently pressed in a different MR, instead of creating a new pipeline for the target branch,
 it creates a new pipeline targeting the merge result of the previous MR plus the target branch.
 Pipelines invalidated through failures are immediately canceled and requeued.
@@ -83,7 +83,7 @@ button while the latest pipeline is running.
 
 ## Immediately merge a merge request with a merge train
 
-In case, you have a high-priority merge request (e.g. critical patch) to be merged urgently,
+In the case where you have a high-priority merge request (for example, a critical patch) to be merged urgently,
 you can use **Merge Immediately** option for bypassing the merge train.
 This is the fastest option to get the change merged into the target branch.
 

doc/ci/multi_project_pipelines.md

@@ -38,7 +38,7 @@ Let's assume you deploy your web app from different projects in GitLab:
 - One for the paid version add-ons, which also pass through builds and tests
 - One for the documentation, which also builds, tests, and deploys with an SSG
 
-With Multi-Project Pipelines, you can visualize the entire pipeline, including all stages of builds and tests for the three projects.
+With Multi-Project Pipelines you can visualize the entire pipeline, including all build and test stages for the three projects.
 
 ## Triggering multi-project pipelines through API
 

doc/ci/runners/README.md

@@ -195,11 +195,11 @@ We have following jobs in queue:
 
 With the fair usage algorithm jobs are assigned in following order:
 
-1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (i.e. all projects)
+1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (that is, all projects)
 1. Job 4 is next, because 4 is now the lowest job number from projects with no running jobs (Project 1 has a job running)
 1. Job 6 is next, because 6 is now the lowest job number from projects with no running jobs (Projects 1 and 2 have jobs running)
 1. Job 2 is next, because, of projects with the lowest number of jobs running (each has 1), it is the lowest job number
-1. Job 5 is next, because Project 1 now has 2 jobs running, and between Projects 2 and 3, Job 5 is the lowest remaining job number
+1. Job 5 is next, because Project 1 now has 2 jobs running and Job 5 is the lowest remaining job number between Projects 2 and 3.
 1. Lastly we choose Job 3... because it's the only job left
 
 ---
@@ -217,7 +217,7 @@ We have following jobs in queue:
 
 With the fair usage algorithm jobs are assigned in following order:
 
-1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (i.e. all projects)
+1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (that is, all projects)
 1. We finish job 1
 1. Job 2 is next, because, having finished Job 1, all projects have 0 jobs running again, and 2 is the lowest available job number
 1. Job 4 is next, because with Project 1 running a job, 4 is the lowest number from projects running no jobs (Projects 2 and 3)
@@ -307,7 +307,7 @@ Example 2:
 For each Runner you can specify a _maximum job timeout_. Such timeout,
 if smaller than [project defined timeout], will take the precedence. This
 feature can be used to prevent Shared Runner from being appropriated
-by a project by setting a ridiculous big timeout (e.g. one week).
+by a project by setting a ridiculous big timeout (for example, one week).
 
 When not configured, Runner will not override project timeout.
 

doc/ci/triggers/README.md

@@ -167,7 +167,7 @@ build_docs:
   - tags
 ```
 
-Now, whenever a new tag is pushed on project A, the job will run and the
+This means that whenever a new tag is pushed on project A, the job will run and the
 `build_docs` job will be executed, triggering a rebuild of project B. The
 `stage: deploy` ensures that this job will run only after all jobs with
 `stage: test` complete successfully.

doc/ci/yaml/README.md

@@ -2905,7 +2905,7 @@ your configuration file is on. In other words, when using a `include:local`, mak
 sure that both `.gitlab-ci.yml` and the local file are on the same branch.
 
 All [nested includes](#nested-includes) will be executed in the scope of the same project,
-so it is possible to use local, project, remote or template includes.
+so it is possible to use local, project, remote, or template includes.
 
 NOTE: **Note:**
 Including local files through Git submodules paths is not supported.