# HG changeset patch
# User Laurent Peuch <cortex@worlddomination.be>
# Date 1617820455 -7200
#      Wed Apr 07 20:34:15 2021 +0200
# Node ID 5289817998462b086a04e1323507fae601487b89
# Parent  d0c0171384974bd5fbdfb22c23b2cd61a2c80859
doc: explain and recommand how to use templates

diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -4,7 +4,57 @@
 In the `templates/` you can find some of our gitlab-ci templates.
 You can include them in your gitlab-ci.
 
-See [release-new's gitlab-ci](https://forge.extranet.logilab.fr/open-source/release-new/-/blob/branch/default/.gitlab-ci.yml)
+To include them use this snippet:
+
+```yaml
+include:
+  - project: "open-source/gitlab-templates"
+    ref: "branch/default"
+    file:                                       # the stages are:
+      - "templates/no-duplicate-pipelines.yml"  # use workflow to avoid duplicated pipelines
+      - "templates/docker-build.yml"            # build a docker image
+      - "templates/build-debian.yml"            # will build a .deb and upload it to heptapod
+      - "templates/release-on-heptapod.yml"     # this will create a release on heptapod AND uses uploaded .deb by build-debian
+      - "templates/publish-pypi.yml"            # this will release on pypi using "tox -e pypi-publish"
+```
+
+Depending on your templates you will need certains stages **in a specific order**:
+
+```yaml
+stages:
+  # put your testing/linting stages here before
+  # for build-debian.yml
+  - build-debian
+  - upload-deb
+  # for docker-build.yml
+  # for release-on-heptapod.yml
+  - release
+  # for publish-pypi.yml
+  - publish
+```
+
+A recommended configuration for a cube would be:
+
+```yaml
+include:
+  - project: "open-source/gitlab-templates"
+    ref: "branch/default"
+    file:                                       # the stages are:
+      - "templates/no-duplicate-pipelines.yml"  # use workflow to avoid duplicated pipelines
+      - "templates/build-debian.yml"            # will build a .deb and upload it to heptapod
+      - "templates/release-on-heptapod.yml"     # this will create a release on heptapod AND uses uploaded .deb by build-debian
+      - "templates/publish-pypi.yml"            # this will release on pypi using "tox -e pypi-publish"
+
+stages:
+  - lint
+  - test
+  - build-debian
+  - upload-deb
+  - release
+  - publish
+```
+
+You can also refer to [release-new's gitlab-ci](https://forge.extranet.logilab.fr/open-source/release-new/-/blob/branch/default/.gitlab-ci.yml)
 for instance, to see how it can be used.
 
 You can also find the official documentation [here](https://docs.gitlab.com/ee/ci/yaml/includes.html),