From 1cb64d9e3a48452d2eefab2792a407fe20efb024 Mon Sep 17 00:00:00 2001
From: Christophe Chaudier <christophe@lydra.fr>
Date: Tue, 9 Feb 2021 11:42:27 +0100
Subject: [PATCH] docs: describe overloading

---
 README-fr.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++----
 README.md    |  7 +++--
 2 files changed, 71 insertions(+), 9 deletions(-)

diff --git a/README-fr.md b/README-fr.md
index 9d8ca3b..df7fba2 100644
--- a/README-fr.md
+++ b/README-fr.md
@@ -1,5 +1,7 @@
 # Gitlab-ci templates
 
+[🇬🇧 English version](README.md)
+
 Simplifiez vos pipelines GitLab ! 🥰
 Une collection utile de *templates* et de *librairies* pour gitlab-ci.
 
@@ -58,6 +60,17 @@ Ce fichier contient la liste des étapes de base de la CI.
 Il faut l'inclure en premier quand on veut utiliser les _templates_ de ce dépôt.
 Il contient aussi les modèles de base des jobs.
 
+Vous pouvez utiliser ces modèles pour concevoir vos propres jobs.
+
+```yaml
+node::test:
+  extends: .base_tpl
+  stage: test
+  script:
+    - make test
+
+```
+
 
 #### Les étapes
 
@@ -166,8 +179,8 @@ Par exemple pour builder deux images docker donc les Dokerfiles sont `front/Doke
 # .gitlab-ci.yml
 
 include:
-  - 'https://gitlab.com/lydra/gitlab-ci-templates/gci-templates/stages.yml'
-  - 'https://gitlab.com/lydra/gitlab-ci-templates/gci-templates/job/container/delivery.yml'
+  - 'https://gitlab.com/lydra/gitlab-ci-templates/-/raw/master/gci-templates/stages.yml'
+  - 'https://gitlab.com/lydra/gitlab-ci-templates/-/raw/master/gci-templates/job/container/delivery.yml'
 
 container:delivery:front:
   extends: "container:delivery"
@@ -180,11 +193,61 @@ container:delivery:back:
   working_directory: "back"
 ```
 
-## Pour aller plus loin
-- [La référence de `.gitlab-ci.yml`](https://docs.gitlab.com/ce/ci/yaml).
 
+#### Surcharge de job
 
-[🇬🇧 English version](README.md)
+Dans votre fichier de CI quand vous importez un fichier de job celui-ci va s’exécuter tel qu'il a été défini.
+Si vous voulez modifier son comportement alors vous pouvez le surcharger en redéfinissant les parties qui vous intéressent.
+La surcharge détourne la fonctionnalité de [fusion de gitlab-ci](https://docs.gitlab.com/ce/ci/yaml/#merge-details).
+C'est pour ça qu'il est important de bien comprendre que GitLab est capable de fusionner des hachages mais pas des tableaux.
+La surcharge fonctionne car dans GitLab c'est toujours les clés du dernier membre qui remplace ce qui est défini avant.
+
+Par exemple les `variables:` s’additionnent là ou les `tags:` ou le `script:` se remplacent.
+
+
+##### Exemple d'utilisation
+
+Je veux utiliser `npm ci` à la place de `yarn build` pour construire mon application node.
+Il faut donc que je surcharge le script du job `node::build`.
+
+Mon `.gitlab-ci.yml` devra être comme ça :
+
+```yaml
+# .gitlab-ci.yml
+
+include:
+  - 'https://gitlab.com/lydra/gitlab-ci-templates/-/raw/master/gci-templates/stages.yml'
+  - 'https://gitlab.com/lydra/gitlab-ci-templates/-/raw/master/gci-templates/job/node/build.yml'
+
+node::build:
+  script:
+    - npm ci
+```
+
+Seule la partie script sera modifiée, toute le reste de la définition du job `node::build` sera comme dans le fichier `https://gitlab.com/lydra/gitlab-ci-templates/-/raw/master/gci-templates/job/node/build.yml`
+
+Ce qui donne comme résultat :
+
+```yaml
+node::build:
+  image: node:14.15.4-slim
+  stage: build
+  variables:
+    working_directory: "$CI_PROJECT_DIR"
+  cache:
+    policy: push
+    key: "node-$CI_COMMIT_REF_SLUG"
+    paths:
+      - node_modules
+  before_script:
+    - cd $working_directory
+  script:
+    - npm ci
+```
+
+
+## Pour aller plus loin
+- [La référence de `.gitlab-ci.yml`](https://docs.gitlab.com/ce/ci/yaml).
 
 
 ---
diff --git a/README.md b/README.md
index c565f4d..83ca7ba 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # gitlab-ci-templates
 
+[🇫🇷 French version](README-fr.md)
+
 A collection of useful templates and includes for gitlab-ci.
 
 All files contains one stage and are named `stage-name.yml`
@@ -19,7 +21,4 @@ This directory contains job *templates*.
 Each job is folded by type or technology in sub-directory.
 
 ---
-Icon made by [Freepik](https://www.freepik.com) from [www.flaticon.com](https://www.flaticon.com)
-is licensed by [CC 3.0 BY](http://creativecommons.org/licenses/by/3.0)
-
-[French doc](README-fr.md)
+Icon made by [Freepik](https://www.freepik.com) from [www.flaticon.com](https://www.flaticon.com) is licensed by [CC 3.0 BY](http://creativecommons.org/licenses/by/3.0)
-- 
GitLab