Update jobs.yml docs to reflect subset-modulo-carve-outs relationship

Author: jieyouxu

src/ci/github-actions/jobs.yml

@@ -124,9 +124,16 @@ jobs:
     <<: *job-linux-36c-codebuild
 
 
-# Jobs that run on each push to a pull request (PR)
-# These jobs automatically inherit envs.pr, to avoid repeating
-# it in each job definition.
+# Jobs that run on each push to a pull request (PR).
+#
+# These jobs automatically inherit envs.pr, to avoid repeating it in each job
+# definition.
+#
+# PR CI jobs will be automatically registered as Auto CI jobs or overriden. When
+# automatically registered, the PR CI job configuration will be copied as an
+# Auto CI job but with `continue_on_error` overriden to `false` (to fail-fast).
+# When overriden, `citool` will check for equivalence between the PR and CI job
+# of the same name modulo `continue_on_error` and `env`.
 pr:
   - name: pr-check-1
     <<: *job-linux-4c
@@ -177,9 +184,15 @@ optional:
       IMAGE: pr-check-1
     <<: *job-linux-4c
 
-# Main CI jobs that have to be green to merge a commit into master
-# These jobs automatically inherit envs.auto, to avoid repeating
-# it in each job definition.
+# Main CI jobs that have to be green to merge a commit into master.
+#
+# These jobs automatically inherit envs.auto, to avoid repeating it in each job
+# definition.
+#
+# Auto jobs may not specify `continue_on_error: true`, and thus will fail-fast.
+#
+# Unless explicitly overriden, PR CI jobs will be automatically registered as
+# Auto CI jobs.
 auto:
   #############################
   #   Linux/Docker builders   #