Merge branch 'docs-yaml-ing-using' into 'master'

Copy edit yaml reference doc, focusing on "using"

See merge request gitlab-org/gitlab!53121

doc/ci/yaml/README.md

@@ -72,7 +72,7 @@ can't be used as job names:
 
 ### Reserved keywords
 
-If you get a validation error when using specific values (for example, `true` or `false`), try to:
+If you get a validation error when you use specific values (for example, `true` or `false`), try to:
 
 - Quote them.
 - Change them to a different form. For example, `/bin/true`.
@@ -477,17 +477,16 @@ include:
 
 #### `include:remote`
 
-Use `include:remote` to include a file from a different location,
-using HTTP/HTTPS, referenced by the full URL. The remote file must be
-publicly accessible by a GET request, because authentication schemas
-in the remote URL are not supported. For example:
+Use `include:remote` with a full URL to include a file from a different location.
+The remote file must be publicly accessible by an HTTP/HTTPS `GET` request, because
+authentication in the remote URL is not supported. For example:
 
 ```yaml
 include:
-  - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
+  - remote: 'https://gitlab.com/example-project/-/raw/master/.gitlab-ci.yml'
 ```
 
-All [nested includes](#nested-includes) are executed without context as a public user,
+All [nested includes](#nested-includes) execute without context as a public user,
 so you can only `include` public projects or templates.
 
 #### `include:template`
@@ -732,7 +731,7 @@ You can use special syntax in [`script`](README.md#script) sections to:
 
 `stage` is defined per-job and relies on [`stages`](#stages), which is defined
 globally. Use `stage` to define which stage a job runs in, and jobs of the same
-`stage` are executed in parallel (subject to [certain conditions](#using-your-own-runners)). For example:
+`stage` are executed in parallel (subject to [certain conditions](#use-your-own-runners)). For example:
 
 ```yaml
 stages:
@@ -765,7 +764,7 @@ job 5:
   script: make something useful at the end of pipeline
 ```
 
-#### Using your own runners
+#### Use your own runners
 
 When you use your own runners, each runner runs only one job at a time by default.
 Jobs can run in parallel if they run on different runners.
@@ -822,11 +821,16 @@ For example, the following are equivalent configuration:
 
 > Introduced in GitLab 11.3.
 
-`extends` defines entry names that a job that uses `extends`
-inherits from.
+Use `extends` to reuse configuration sections. It's an alternative to [YAML anchors](#anchors)
+and is a little more flexible and readable. You can use `extends` to reuse configuration
+from [included configuration files](#use-extends-and-include-together).
 
-It's an alternative to using [YAML anchors](#anchors) and is a little
-more flexible and readable:
+In this example, the `rspec` job uses the configuration from the `.tests` template job.
+GitLab:
+
+- Performs a reverse deep merge based on the keys.
+- Merges the `.tests` content with the `rspec` job.
+- Doesn't merge the values of the keys.
 
 ```yaml
 .tests:
@@ -844,13 +848,7 @@ rspec:
       - $RSPEC
 ```
 
-In the example above, the `rspec` job inherits from the `.tests` template job.
-GitLab performs a reverse deep merge based on the keys. GitLab:
-
-- Merges the `rspec` contents into `.tests` recursively.
-- Doesn't merge the values of the keys.
-
-The result is this `rspec` job, where `script: rake test` is overwritten by `script: rake rspec`:
+The result is this `rspec` job:
 
 ```yaml
 rspec:
@@ -863,10 +861,8 @@ rspec:
       - $RSPEC
 ```
 
-If you do want to include the `rake test`, see [`before_script`](#before_script) or [`after_script`](#after_script).
-
 `.tests` in this example is a [hidden job](#hide-jobs), but it's
-possible to inherit from regular jobs as well.
+possible to extend configuration from regular jobs as well.
 
 `extends` supports multi-level inheritance. You should avoid using more than three levels,
 but you can use as many as eleven. The following example has two levels of inheritance:
@@ -960,30 +956,32 @@ Note that in the example above:
 - `script` does not merge, but `script: ['rake rspec']` overwrites
   `script: ['echo "Hello world!"']`. You can use [YAML anchors](#anchors) to merge arrays.
 
-#### Using `extends` and `include` together
+#### Use `extends` and `include` together
 
-`extends` works across configuration files combined with `include`.
+To reuse configuration from different configuration files,
+combine `extends` and [`include`](#include).
 
-For example, if you have a local `included.yml` file:
+In this example, a `script` is defined in the `included.yml` file.
+Then, in the `.gitlab-ci.yml` file, you use `extends` to refer
+to the contents of the `script`:
 
-```yaml
-.template:
-  script:
-    - echo Hello!
-```
+- `included.yml`:
 
-Then, in the `.gitlab-ci.yml` file:
+  ```yaml
+  .template:
+    script:
+      - echo Hello!
+  ```
 
-```yaml
-include: included.yml
+- `.gitlab-ci.yml`:
 
-useTemplate:
-  image: alpine
-  extends: .template
-```
+  ```yaml
+  include: included.yml
 
-This example runs a job called `useTemplate` that runs `echo Hello!` as defined in
-the `.template` job, and uses the `alpine` Docker image as defined in the local job.
+  useTemplate:
+    image: alpine
+    extends: .template
+  ```
 
 ### `rules`
 
@@ -1052,7 +1050,7 @@ The job is not added to the pipeline:
   `when: always`.
 - If a rule matches, and has `when: never` as the attribute.
 
-For example, using `if` clauses to strictly limit when jobs run:
+This example uses `if` to strictly limit when jobs run:
 
 ```yaml
 job:
@@ -1064,8 +1062,6 @@ job:
     - if: '$CI_PIPELINE_SOURCE == "schedule"'
 ```
 
-In this example:
-
 - If the pipeline is for a merge request, the first rule matches, and the job
   is added to the [merge request pipeline](../merge_request_pipelines/index.md)
   with attributes of:
@@ -1139,7 +1135,7 @@ There are multiple ways to avoid duplicate pipelines:
   or push (branch) pipelines only.
 
 - Rewrite the rules to run the job only in very specific cases,
-  and avoid using a final `when:` rule:
+  and avoid a final `when:` rule:
 
   ```yaml
   job:
@@ -1256,7 +1252,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable:
 |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `api`                         | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline).                                                                                                                                    |
 | `chat`                        | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command.                                                                                                                                                 |
-| `external`                    | When using CI services other than GitLab.                                                                                                                                                                                        |
+| `external`                    | When you use CI services other than GitLab.                                                                                                                                                                                        |
 | `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests).                                            |
 | `merge_request_event`         | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
 | `parent_pipeline`             | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline.                |
@@ -1383,7 +1379,9 @@ You can use The `$` character for both variables and paths. For example, if the
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4.
 
 `exists` accepts an array of paths and matches if any of these paths exist
-as files in the repository:
+as files in the repository.
+
+In this example, `job` runs if a `Dockerfile` exists anywhere in the repository:
 
 ```yaml
 job:
@@ -1408,15 +1406,14 @@ job:
 Glob patterns are interpreted with Ruby [File.fnmatch](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch)
 with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`.
 
-For performance reasons, using `exists` with patterns is limited to 10,000
-checks. After the 10,000th check, rules with patterned globs always match.
+For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns. After the 10,000th check, rules with patterned globs always match.
 
 #### `rules:allow_failure`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8.
 
 You can use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail, or a manual job to
-wait for action, without stopping the pipeline itself. All jobs using `rules:` default to `allow_failure: false`
+wait for action, without stopping the pipeline itself. All jobs that use `rules:` default to `allow_failure: false`
 if `allow_failure:` is not defined.
 
 The rule-level `rules:allow_failure` option overrides the job-level
@@ -1532,12 +1529,10 @@ rules that use both `||` and `&&` may evaluate with an unexpected order of opera
 ### `only`/`except` (basic)
 
 NOTE:
-The [`rules`](#rules) syntax is an improved, more powerful solution for defining
-when jobs should run or not. Consider using `rules` instead of `only/except` to get
-the most out of your pipelines.
+`only` and `except` are not being actively developed. To define when
+to add jobs to pipelines, use [`rules`](#rules).
 
-`only` and `except` are two keywords that set a job policy to limit when
-jobs are created:
+`only` and `except` are two keywords that determine when to add jobs to pipelines:
 
 1. `only` defines the names of branches and tags the job runs for.
 1. `except` defines the names of branches and tags the job does
@@ -1557,7 +1552,7 @@ In addition, `only` and `except` can use special keywords:
 | `api`                    | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline).                                                                                                                                    |
 | `branches`               | When the Git reference for a pipeline is a branch.                                                                                                                                                                               |
 | `chat`                   | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command.                                                                                                                                                 |
-| `external`               | When using CI services other than GitLab.                                                                                                                                                                                        |
+| `external`               | When you use CI services other than GitLab.                                                                                                                                                                                        |
 | `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)).                                           |
 | `merge_requests`         | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
 | `pipelines`              | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. |
@@ -1780,7 +1775,7 @@ The `variables` keyword defines variable expressions.
 
 These expressions determine whether or not a job should be created.
 
-Examples of using variable expressions:
+Examples of variable expressions:
 
 ```yaml
 deploy:
@@ -1819,15 +1814,14 @@ job1:
 
 > `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4.
 
-Using the `changes` keyword with `only` or `except` makes it possible to define if
-a job should be created based on files modified by a Git push event.
+Use the `changes` keyword with `only` to run a job, or with `except` to skip a job,
+when a Git push event modifies a file.
 
-Use the `only:changes` policy for pipelines triggered by the following
-refs only:
+Use `only:changes` with pipelines triggered by the following refs only:
 
 - `branches`
 - `external_pull_requests`
-- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](#using-onlychanges-with-pipelines-for-merge-requests))
+- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](#use-onlychanges-with-pipelines-for-merge-requests))
 
 WARNING:
 In pipelines with [sources other than the three above](../variables/predefined_variables.md)
@@ -1835,7 +1829,13 @@ In pipelines with [sources other than the three above](../variables/predefined_v
 You can configure jobs to use `only: changes` with other `only: refs` keywords. However,
 those jobs ignore the changes and always run.
 
-A basic example of using `only: changes`:
+In this example, when you push commits to an existing branch, the `docker build` job
+runs only if any of these files change:
+
+- The `Dockerfile` file.
+- Files in the `docker/scripts/` directory.
+- Files and subdirectories in the `dockerfiles` directory.
+- Files with `rb`, `py`, `sh` extensions in the `more_scripts` directory.
 
 ```yaml
 docker build:
@@ -1850,21 +1850,13 @@ docker build:
       - more_scripts/*.{rb,py,sh}
 ```
 
-When you push commits to an existing branch,
-the `docker build` job is created, but only if changes were made to any of the following:
-
-- The `Dockerfile` file.
-- Any of the files in the `docker/scripts/` directory.
-- Any of the files and subdirectories in the `dockerfiles` directory.
-- Any of the files with `rb`, `py`, `sh` extensions in the `more_scripts` directory.
-
 WARNING:
 If you use `only:changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds),
-you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected.
+you should [also use `only:merge_requests`](#use-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected.
 
 You can also use glob patterns to match multiple files in either the root directory
 of the repository, or in _any_ directory in the repository. However, they must be wrapped
-in double quotes or GitLab can't parse them. For example:
+in double quotes or GitLab can't parse them:
 
 ```yaml
 test:
@@ -1893,10 +1885,10 @@ the `build` job is still skipped. The job does not run for any of the files.
 
 Read more about how to use this feature with:
 
-- [New branches or tags *without* pipelines for merge requests](#using-onlychanges-without-pipelines-for-merge-requests).
-- [Scheduled pipelines](#using-onlychanges-with-scheduled-pipelines).
+- [New branches or tags *without* pipelines for merge requests](#use-onlychanges-without-pipelines-for-merge-requests).
+- [Scheduled pipelines](#use-onlychanges-with-scheduled-pipelines).
 
-##### Using `only:changes` with pipelines for merge requests
+##### Use `only:changes` with pipelines for merge requests
 
 With [pipelines for merge requests](../merge_request_pipelines/index.md),
 it's possible to define a job to be created based on files modified
@@ -1946,7 +1938,7 @@ it doesn't matter that an earlier pipeline failed because of a change that has n
 When you use this configuration, ensure that the most recent pipeline
 properly corrects any failures from previous pipelines.
 
-##### Using `only:changes` without pipelines for merge requests
+##### Use `only:changes` without pipelines for merge requests
 
 Without [pipelines for merge requests](../merge_request_pipelines/index.md), pipelines
 run on branches or tags that don't have an explicit association with a merge request.
@@ -1954,14 +1946,13 @@ In this case, a previous SHA is used to calculate the diff, which is equivalent
 This can result in some unexpected behavior, including:
 
 - When pushing a new branch or a new tag to GitLab, the policy always evaluates to true.
-- When pushing a new commit, the changed files are calculated using the previous commit
+- When pushing a new commit, the changed files are calculated by using the previous commit
   as the base SHA.
 
-##### Using `only:changes` with scheduled pipelines
+##### Use `only:changes` with scheduled pipelines
 
-`only:changes` always evaluates as "true" in [Scheduled pipelines](../pipelines/schedules.md).
-All files are considered to have "changed" when a scheduled pipeline
-runs.
+`only:changes` always evaluates as true in [Scheduled pipelines](../pipelines/schedules.md).
+All files are considered to have changed when a scheduled pipeline runs.
 
 ### `needs`
 
@@ -2056,14 +2047,11 @@ To disable directed acyclic graphs (DAG), set the limit to `0`.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.6.
 
-When using `needs`, artifact downloads are controlled with `artifacts: true` (default) or `artifacts: false`.
-
-In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword
-with `needs` to control artifact downloads in jobs. `dependencies` is still valid
-in jobs that do not use `needs`.
+Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are
+downloaded in jobs that use `needs`.
 
-In the example below, the `rspec` job downloads the `build_job` artifacts, while the
-`rubocop` job doesn't:
+In this example, the `rspec` job downloads the `build_job` artifacts, but the
+`rubocop` job does not:
 
 ```yaml
 build_job:
@@ -2085,9 +2073,11 @@ rubocop:
       artifacts: false
 ```
 
-Additionally, in the three syntax examples below, the `rspec` job downloads the artifacts
-from all three `build_jobs`. `artifacts` is true for `build_job_1` and
-**defaults** to true for both `build_job_2` and `build_job_3`.
+In this example, the `rspec` job downloads the artifacts from all three `build_jobs`.
+`artifacts` is:
+
+- Set to true for `build_job_1`.
+- Defaults to true for both `build_job_2` and `build_job_3`.
 
 ```yaml
 rspec:
@@ -2098,6 +2088,9 @@ rspec:
     - build_job_3
 ```
 
+In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword
+with `needs`.
+
 #### Cross project artifact downloads with `needs` **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.7.
@@ -2255,10 +2248,11 @@ osx job:
 ### `allow_failure`
 
 Use `allow_failure` when you want to let a job fail without impacting the rest of the CI
-suite.
-The default value is `false`, except for [manual](#whenmanual) jobs using the
-`when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs
-default to false, *including* `when: manual` jobs.
+suite. The default value is `false`, except for [manual](#whenmanual) jobs that use
+the `when: manual` syntax.
+
+In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`,
+*including* `when: manual` jobs.
 
 When `allow_failure` is set to `true` and the job fails, the job shows an orange warning in the UI.
 However, the logical flow of the pipeline considers the job a
@@ -2825,7 +2819,8 @@ to download cache that's tagged with `test`.
 If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to
 specify a cache to use when none exists.
 
-For example:
+In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined
+by the `CACHE_FALLBACK_KEY` variable:
 
 ```yaml
 variables:
@@ -2837,9 +2832,6 @@ cache:
     - binaries/
 ```
 
-In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined
-by the `CACHE_FALLBACK_KEY` variable.
-
 ##### `cache:key:files`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5.
@@ -3616,7 +3608,7 @@ but with different variable values for each instance of the job.
 There can be from 2 to 50 jobs.
 
 Jobs can only run in parallel if there are multiple runners, or a single runner is
-[configured to run multiple jobs concurrently](#using-your-own-runners).
+[configured to run multiple jobs concurrently](#use-your-own-runners).
 
 Every job gets the same `CI_NODE_TOTAL` [environment variable](../variables/README.md#predefined-environment-variables) value, and a unique `CI_NODE_INDEX` value.