Resolve "Improve CI template organization"

Closes #35 (closed)

README.adoc

@@ -6,22 +6,45 @@ This repository contains miscellaneous resources that need to be accessible with
 
 Two templates with default CI pipeline configurations are provided, for any repo to make use of:
 
+- `.gitlab-industrial-ci-no-rosinstall.yml`
+- `.gitlab-industrial-ci-with-rosinstall.yml`
+
+=== ROS distribution selection
+These pipelines will try to detect the ROS distro from the branch name. For example, if the branch starts with `noetic-` it will build for noetic. If the branch doesn't start with any ROS distro, it will build the default distro, which can be specified with the variable `DEFAULT_DISTRO`. For convenience and backwards compatibility, some templates are provided that already set this variable:
+
 - `.gitlab-industrial-ci-kinetic-no-rosinstall.yml`
-- `.gitlab-industrial-ci-kinetic-with-rosinstall.yml`
+- `.gitlab-industrial-ci-melodic-no-rosinstall.yml`
+- `.gitlab-industrial-ci-noetic-no-rosinstall.yml`
+- And the same with the `with-rosinstall` files.
 
-Both define basically the same pipeline, consisting of the following stages and jobs:
+=== Multiple ROS distributions
+
+If a repo wants to compile using multiple distributions, one can specify them by setting the `BUILD` variables:
+
+```yml
+include: 'https://git.code.tecnalia.com/tecnalia_robotics-public/gitlab_templates/raw/master/.gitlab-industrial-ci-with-rosinstall.yml'
+
+variables:
+    BUILD_KINETIC: 1
+    BUILD_MELODIC: 1
+    BUILD_NOETIC: 1
+```
+
+=== Pipeline
+
+All files follow the same pipeline, consisting of the following stages and jobs:
 
-- Stage: `precheck`
-  * Check python syntax
 - Stage: `build`
+  * Check python syntax
   * Run `industrial_ci`
+    ** Uses the ros distro defined above
     ** Uses `flexbotics-base-devel` as a starting image
     ** Runs link:scripts/ci_run_entry_points.sh[] in the `BEFORE_SCRIPT` stage, which in turn finds and runs every `ci_entry_script.bash` script found in the source tree (target repo + repos from `.rosinstall`)
   * Only when tags are pushed:
     ** Run some cleanup in the `industrial_ci` context (e.g. delete sources)
     ** Commit image used by `industrial_ci`
     ** Build deployment image on top of it and push it to our registry
-- Stage: `postcheck` (jobs in this stage are allowed to fail)
+- Stage: `.post` (jobs in this stage are allowed to fail)
   * Check `bash`/`sh` script syntax
   * Check Markdown syntax
   * Check files have no trailing whitespace and are UTF-8 encoded