Merge branch 'docs-changes-config-clarification' into 'master'

Add warnings about changes: to CI Config docs

See merge request gitlab-org/gitlab!21685

doc/ci/variables/predefined_variables.md

@@ -86,7 +86,7 @@ future GitLab releases.**
 | `CI_PAGES_URL`                                | 11.8   | all    | URL to GitLab Pages-built pages. Always belongs to a subdomain of `CI_PAGES_DOMAIN`.                                                                                                                                                                                                                                                                       |
 | `CI_PIPELINE_ID`                              | 8.10   | all    | The unique id of the current pipeline that GitLab CI uses internally                                                                                                                                                                                                                                                                                       |
 | `CI_PIPELINE_IID`                             | 11.0   | all    | The unique id of the current pipeline scoped to project                                                                                                                                                                                                                                                                                                    |
-| `CI_PIPELINE_SOURCE`                          | 10.0   | all    | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, `pipeline` and `merge_request_event`. For pipelines created before GitLab 9.5, this will show as `unknown`                                                                                                                                                          |
+| `CI_PIPELINE_SOURCE`                          | 10.0   | all    | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, `pipeline`, `external`, `chat`, `merge_request_event`, and `external_pull_request_event`. For pipelines created before GitLab 9.5, this will show as `unknown`                                                                                                                                                          |
 | `CI_PIPELINE_TRIGGERED`                       | all    | all    | The flag to indicate that job was [triggered](../triggers/README.md)                                                                                                                                                                                                                                                                                       |
 | `CI_PIPELINE_URL`                             | 11.1   | 0.5    | Pipeline details URL                                                                                                                                                                                                                                                                                                                                       |
 | `CI_PROJECT_DIR`                              | all    | all    | The full path where the repository is cloned and where the job is run. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see [Advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) for GitLab Runner. |

doc/ci/yaml/README.md

@@ -729,7 +729,18 @@ Learn more about [variables expressions](../variables/README.md#environment-vari
 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.
 
-For example:
+This means the `only:changes` policy is useful for pipelines where:
+
+- `$CI_PIPELINE_SOURCE == 'push'`
+- `$CI_PIPELINE_SOURCE == 'merge_request_event'`
+- `$CI_PIPELINE_SOURCE == 'external_pull_request_event'`
+
+If there is no Git push event, such as for pipelines with
+[sources other than the three above](../variables/predefined_variables.html#variables-reference),
+`changes` cannot determine if a given file is new or old, and will always
+return true.
+
+A basic example of using `only: changes`:
 
 ```yaml
 docker build:
@@ -910,8 +921,9 @@ at all, the behavior defaults to `job:when`, which continues to default to
 
 #### `rules:changes`
 
-`changes` works exactly the same way as [`only`/`except`](#onlychangesexceptchanges),
-accepting an array of paths.
+`rules: changes` works exactly the same way as `only: changes` and `except: changes`,
+accepting an array of paths. Similarly, it will always return true if there is no
+Git push event. See [`only/except: changes`](#onlychangesexceptchanges) for more information.
 
 For example: