[librsvg] gitlabci: Document the different stage setup.

[Jordan Petridis <jpetridis src gnome org>]

commit 8382e94e3d3c694a3cb0412d7eb9a64d3d1aefa0
Author: Jordan Petridis <jordanpetridis protonmail com>
Date:   Tue Mar 20 07:08:18 2018 +0200

    gitlabci: Document the different stage setup.

 .gitlab-ci.yml | 151 ++++++++++++++++++++++++++-------------------------------
 1 file changed, 70 insertions(+), 81 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 6c817aa5..f20d0754 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -56,7 +56,36 @@ stages:
       - .cargo_cache/
       - ccache/
 
-# TEST STAGE
+
+# Jobs that are marked with stage_1 will be run on every commit, across every
+# fork and branch. This only serves as documentation since it's equivelant to
+# ommiting only: key. Thus why stage_1 jobs might not be marked.
+.test_stage_1: &stage_1
+  only: {}
+
+# Jobs that are marked as stage 2 will be run for every commit
+# at GNOME/librsvg/master too. Ideal targets for this stage are
+# debug cross_distro tests, and debug cross_arch tests to avoid
+# breakign i386 and arm builds again.
+.test_stage_2: &stage_2
+  only:
+    # When branching a stable branch,
+    # update the following line from master to branch's name.
+    - master@GNOME/librsvg
+    - schedules
+    - tags
+    - web
+
+# Jobs that are marked as stage 3 will only run on scheduled pipelines.
+# Ideal targets for this stage are expensive task, that only need to be run
+# on a regular time interval. Ex testing all the gcc/rustc version that we target
+.test_stage_3: &stage_3
+  only:
+    - schedules
+    - tags
+    - web
+
+# STAGE 1 TESTS
 ########################################################################
 
 fedora:test:
@@ -73,8 +102,31 @@ fedora:test_release:
     LIBRSVG_DEBUG: "no"
   <<: *distro_test
 
+# STAGE 1 LINTS
+########################################################################
+
+# Configure and run rustfmt on nightly
+# Exits and builds fails on bad format
+rustfmt:
+  image: $RUSTFMT_NIGHTLY
+  stage: lint
+  script:
+    - rustc --version && cargo --version
+    - cargo fmt --all -- --write-mode=diff
+
 
-# CROSS DISTRO AMD64 TEST STAGE
+# Configure and run clippy on nightly
+# Only fails on errors atm.
+clippy:
+  image: $CLIPPY_NIGHTLY
+  stage: lint
+  script:
+    - rustc --version && cargo --version
+    - cargo install clippy --force
+    - cargo clippy --all
+  when: manual
+
+# STAGE 2 CROSS DISTRO TESTS
 #######################################################################
 
 fedora:rawhide:
@@ -83,11 +135,7 @@ fedora:rawhide:
   variables:
     LIBRSVG_DEBUG: "yes"
   <<: *distro_test
-  only:
-    - master@GNOME/librsvg
-    - schedules
-    - tags
-    - web
+  <<: *stage_2
 
 opensuse:tumbleweed:
   image: $AMD64_OPENSUSE_TUMBLEWEED
@@ -95,11 +143,7 @@ opensuse:tumbleweed:
   variables:
     LIBRSVG_DEBUG: "yes"
   <<: *distro_test
-  only:
-    - master@GNOME/librsvg
-    - schedules
-    - tags
-    - web
+  <<: *stage_2
 
 debian:testing:
   image: $AMD64_DEBIAN_TESTING
@@ -107,11 +151,7 @@ debian:testing:
   variables:
     LIBRSVG_DEBUG: "yes"
   <<: *distro_test
-  only:
-    - master@GNOME/librsvg
-    - schedules
-    - tags
-    - web
+  <<: *stage_2
 
 # TODO: Enable this when ubuntu update it's rustc package
 # https://gitlab.gnome.org/GNOME/librsvg/issues/213
@@ -119,14 +159,17 @@ debian:testing:
 #   image: $AMD64_UBUNTU_DEVEL
 #   stage: cross_distro
 #   <<: *distro_test
-#   only:
-#     - master@GNOME/librsvg
-#     - schedules
-#     - tags
-#     - web
+#   <<: *stage_2
 
+debian:testing_i386:
+  image: $I386_DEBIAN_TESTING
+  stage: cross_distro
+  variables:
+    LIBRSVG_DEBUG: "yes"
+  <<: *distro_test
+  <<: *stage_2
 
-# CROSS DISTRO RELEASE AMD64 TEST STAGE
+# STAGE 3 CROSS DISTRO TESTS
 #######################################################################
 
 fedora:rawhide_release:
@@ -135,10 +178,7 @@ fedora:rawhide_release:
   variables:
     LIBRSVG_DEBUG: "no"
   <<: *distro_test
-  only:
-    - schedules
-    - tags
-    - web
+  <<: *stage_3
 
 opensuse:tumbleweed_release:
   image: $AMD64_OPENSUSE_TUMBLEWEED
@@ -146,10 +186,7 @@ opensuse:tumbleweed_release:
   variables:
     LIBRSVG_DEBUG: "no"
   <<: *distro_test
-  only:
-    - schedules
-    - tags
-    - web
+  <<: *stage_3
 
 debian:testing_release:
   image: $AMD64_DEBIAN_TESTING
@@ -157,28 +194,7 @@ debian:testing_release:
   variables:
     LIBRSVG_DEBUG: "no"
   <<: *distro_test
-  only:
-    - schedules
-    - tags
-    - web
-
-# CROSS DISTRO i386
-#######################################################################
-
-debian:testing_i386:
-  image: $I386_DEBIAN_TESTING
-  stage: cross_distro
-  variables:
-    LIBRSVG_DEBUG: "yes"
-  <<: *distro_test
-  only:
-    - master@GNOME/librsvg
-    - schedules
-    - tags
-    - web
-
-# CROSS DISTRO RELEASE i386
-#######################################################################
+  <<: *stage_3
 
 debian:testing_release_i386:
   image: $I386_DEBIAN_TESTING
@@ -186,31 +202,4 @@ debian:testing_release_i386:
   variables:
     LIBRSVG_DEBUG: "no"
   <<: *distro_test
-  only:
-    - schedules
-    - tags
-    - web
-
-# LINT STAGE
-#######################################################################
-
-# Configure and run rustfmt on nightly
-# Exits and builds fails on bad format
-rustfmt:
-  image: $RUSTFMT_NIGHTLY
-  stage: lint
-  script:
-    - rustc --version && cargo --version
-    - cargo fmt --all -- --write-mode=diff
-
-
-# Configure and run clippy on nightly
-# Only fails on errors atm.
-clippy:
-  image: $CLIPPY_NIGHTLY
-  stage: lint
-  script:
-    - rustc --version && cargo --version
-    - cargo install clippy --force
-    - cargo clippy --all
-  when: manual
+  <<: *stage_3