From 6481b44b76630c744b9f67d9c5faf686ccf8244e Mon Sep 17 00:00:00 2001
From: Ronald van Zon <rvzon84@gmail.com>
Date: Mon, 8 Oct 2018 11:35:23 +0000
Subject: [PATCH] Update explanation about the `extends` feature

---
 doc/ci/yaml/README.md | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 15dde36cca8..8b770495853 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -102,10 +102,13 @@ rspec:
       - $RSPEC
 ```
 
-In the example above, the `rspec` job is going to inherit from the `.tests`
-template job. GitLab will perform a reverse deep merge, which means that it will
-merge the `rspec` contents into `.tests` recursively, and this is going to result in
-the following `rspec` job:
+In the example above, the `rspec` job inherits from the `.tests` template job. 
+GitLab will perform a reverse deep merge based on the keys. GitLab will:
+
+- Merge the `rspec` contents into `.tests` recursively.
+- Not merge the values of the keys.
+
+This results in the following `rspec` job:
 
 ```yaml
 rspec:
@@ -118,6 +121,11 @@ rspec:
       - $RSPEC
 ```
 
+NOTE: **Note:**
+Note that `script: rake test` has been overwritten by `script: rake rspec`.
+
+If you do want to include the `rake test`, have a look at [before_script-and-after_script](#before_script-and-after_script).
+
 `.tests` in this example is a [hidden key](#hidden-keys-jobs), but it's
 possible to inherit from regular jobs as well.