Merge branch '34013-clarifying-only-key-functionality-yaml-doc' into 'master'

Documentation update to clarify that only key includes a step if any conditions match

See merge request gitlab-org/gitlab!24511

doc/ci/yaml/README.md

@@ -605,6 +605,24 @@ With `only`, individual keys are logically joined by an AND:
 
 > (any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active)
 
+In the example below, the `test` job will `only` be created when **all** of the following are true:
+
+- The pipeline has been [scheduled](../../user/project/pipelines/schedules.md) **or** runs for `master`.
+- The `variables` keyword matches.
+- The `kubernetes` service is active on the project.
+
+```yaml
+test:
+  script: npm run test
+  only:
+    refs:
+      - master
+      - schedules
+    variables:
+      - $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/
+    kubernetes: active
+```
+
 `except` is implemented as a negation of this complete expression:
 
 > NOT((any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active))
@@ -613,6 +631,21 @@ This means the keys are treated as if joined by an OR. This relationship could b
 
 > (any of refs) OR (any of variables) OR (any of changes) OR (if Kubernetes is active)
 
+In the example below, the `test` job will **not** be created when **any** of the following are true:
+
+- The pipeline runs for the `master`.
+- There are changes to the `README.md` file in the root directory of the repo.
+
+```yaml
+test:
+  script: npm run test
+  except:
+    refs:
+      - master
+    changes:
+      - "README.md"
+```
+
 #### `only:refs`/`except:refs`
 
 > `refs` policy introduced in GitLab 10.0.