Refactor the only and except complex section

- Split up refs and kubernetes to their own section
- Use only and except in all headings explicitly
- Document the boolean logic of only and except

doc/ci/yaml/README.md

@@ -402,7 +402,7 @@ job:
   script: echo 'test'
 ```
 
-is translated to
+is translated to:
 
 ```yaml
 job:
@@ -412,49 +412,64 @@ job:
 
 ## `only` and `except` (complex)
 
-> `refs` and `kubernetes` policies introduced in GitLab 10.0
->
-> `variables` policy introduced in 10.7
->
-> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in 11.4
+> - `refs` and `kubernetes` policies introduced in GitLab 10.0.
+> - `variables` policy introduced in GitLab 10.7.
+> - `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in GitLab 11.4.
 
 CAUTION: **Warning:**
 This an _alpha_ feature, and it is subject to change at any time without
 prior notice!
 
-Since GitLab 10.0 it is possible to define a more elaborate only/except job
-policy configuration.
+GitLab supports both simple and complex strategies, so it's possible to use an
+array and a hash configuration scheme.
 
-GitLab now supports both, simple and complex strategies, so it is possible to
-use an array and a hash configuration scheme.
+Four keys are available:
 
-Four keys are now available: `refs`, `kubernetes` and `variables` and `changes`.
+- `refs`
+- `variables`
+- `changes`
+- `kubernetes`
 
-### `refs` and `kubernetes`
+If you use multiple keys under `only` or `except`, they act as an AND. The logic is:
 
-Refs strategy equals to simplified only/except configuration, whereas
-kubernetes strategy accepts only `active` keyword.
+> (any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active)
 
-### `only:variables`
+### `only:refs` and `except:refs`
 
-`variables` keyword is used to define variables expressions. In other words
-you can use predefined variables / project / group or
-environment-scoped variables to define an expression GitLab is going to
-evaluate in order to decide whether a job should be created or not.
+The `refs` strategy can take the same values as the
+[simplified only/except configuration](#only-and-except-simplified).
 
-See the example below. Job is going to be created only when pipeline has been
-scheduled or runs for a `master` branch, and only if kubernetes service is
-active in the project.
+In the example below, the `deploy` job is going to be created only when the
+pipeline has been [scheduled][schedules] or runs for the `master` branch:
 
 ```yaml
-job:
+deploy:
   only:
     refs:
       - master
       - schedules
+```
+
+### `only:kubernetes` and `except:kubernetes`
+
+The `kubernetes` strategy accepts only the `active` keyword.
+
+In the example below, the `deploy` job is going to be created only when the
+Kubernetes service is active in the project:
+
+```yaml
+deploy:
+  only:
     kubernetes: active
 ```
 
+### `only:variables` and `except:variables`
+
+The `variables` keyword is used to define variables expressions. In other words,
+you can use predefined variables / project / group or
+environment-scoped variables to define an expression GitLab is going to
+evaluate in order to decide whether a job should be created or not.
+
 Examples of using variables expressions:
 
 ```yaml
@@ -468,7 +483,7 @@ deploy:
       - $STAGING
 ```
 
-Another use case is exluding jobs depending on a commit message _(added in 11.0)_:
+Another use case is excluding jobs depending on a commit message:
 
 ```yaml
 end-to-end:
@@ -478,11 +493,11 @@ end-to-end:
       - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
 ```
 
-Learn more about variables expressions on [a separate page][variables-expressions].
+Learn more about [variables expressions](../variables/README.md#variables-expressions).
 
-### `only:changes`
+### `only:changes` and `except:changes`
 
-Using `changes` keyword with `only` or `except` makes it possible to define if
+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:
@@ -499,13 +514,13 @@ docker build:
 ```
 
 In the scenario above, if you are pushing multiple commits to GitLab to an
-existing branch, GitLab creates and triggers `docker build` job, provided that
+existing branch, GitLab creates and triggers the `docker build` job, provided that
 one of the commits contains changes to either:
 
 - The `Dockerfile` file.
 - Any of the files inside `docker/scripts/` directory.
-- Any of the files and subfolders inside `dockerfiles` directory.
-- Any of the files with `rb`, `py`, `sh` extensions inside `more_scripts` directory.
+- Any of the files and subdirectories inside the `dockerfiles` directory.
+- Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory.
 
 CAUTION: **Warning:**
 There are some caveats when using this feature with new branches and tags. See
@@ -674,7 +689,7 @@ Manual actions are a special type of job that are not executed automatically,
 they need to be explicitly started by a user. An example usage of manual actions
 would be a deployment to a production environment. Manual actions can be started
 from the pipeline, job, environment, and deployment views. Read more at the
-[environments documentation][env-manual].
+[environments documentation](../environments.md#manually-deploying-to-environments).
 
 Manual actions can be either optional or blocking. Blocking manual actions will
 block the execution of the pipeline at the stage this action is defined in. It's
@@ -1323,7 +1338,7 @@ The test reports are collected regardless of the job results (success or failure
 You can use [`artifacts:expire_in`](#artifacts-expire_in) to set up an expiration
 date for their artifacts.
 
-NOTE: **Note:** 
+NOTE: **Note:**
 If you also want the ability to browse the report output files, include the
 [`artifacts:paths`](#artifactspaths) keyword.
 
@@ -1657,7 +1672,7 @@ rspec:
 ```
 
 NOTE: **Note:**
-`include` requires the external YAML files to have the extensions `.yml` or `.yaml`. 
+`include` requires the external YAML files to have the extensions `.yml` or `.yaml`.
 The external file will not be included if the extension is missing.
 
 You can define it either as a single string, or, in case you want to include
@@ -1709,7 +1724,7 @@ include:
     The remote file must be publicly accessible through a simple GET request, as we don't support authentication schemas in the remote URL.
 
     NOTE: **Note:**
-    In order to include files from another repository inside your local network, 
+    In order to include files from another repository inside your local network,
     you may need to enable the **Allow requests to the local network from hooks and services** checkbox
     located in the **Settings > Network > Outbound requests** section within the **Admin area**.
 
@@ -2195,19 +2210,14 @@ try to quote them, or change them to a different form (e.g., `/bin/true`).
 
 ## Examples
 
-Visit the [examples README][examples] to see a list of examples using GitLab
-CI with various languages.
+See a [list of examples](../examples/README.md "CI/CD examples") for using
+GitLab CI/CD with various languages.
 
-[env-manual]: ../environments.md#manually-deploying-to-environments
-[examples]: ../examples/README.md
 [ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323
-[environment]: ../environments.md
 [ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669
-[variables]: ../variables/README.md
 [ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983
 [ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447
 [ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909
-[schedules]: ../../user/project/pipelines/schedules.md
-[variables-expressions]: ../variables/README.md#variables-expressions
-[ee]: https://about.gitlab.com/gitlab-ee/
-[gitlab-versions]: https://about.gitlab.com/products/
+[environment]: ../environments.md "CI/CD environments"
+[schedules]: ../../user/project/pipelines/schedules.md "Pipelines schedules"
+[variables]: ../variables/README.md "CI/CD variables"