Refactor jjb ci templates

- Add Documentation
- Rearrange anchors for improved maintainability

Change-Id: If69127cb4a26942bcc3f57c5bfc407964c817393
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

diff --git a/jjb/lf-ci-jobs.yaml b/jjb/lf-ci-jobs.yaml
index add785f..37467a5 100644 (file)
--- a/jjb/lf-ci-jobs.yaml
+++ b/jjb/lf-ci-jobs.yaml
@@ -61,14 +61,6 @@
             - file-id: jjbini
               target: '$HOME/.config/jenkins_jobs/jenkins_jobs.ini'
 
-- lf_jjb_file_paths: &lf_jjb_file_paths
-    name: lf-jjb-file-paths
-    file-paths:
-      - compare-type: ANT
-        pattern: '**/*.sh'
-      - compare-type: ANT
-        pattern: '**/*.yaml'
-
 - lf_packer_file_paths: &lf_packer_file_paths
     name: lf-packer-file-paths
     file-paths:
@@ -124,22 +116,29 @@
 
 - lf_jjb_common: &lf_jjb_common
     name: lf-jjb-common
-    project-type: freestyle
-
-    node: '{build-node}'
 
     ######################
     # Default parameters #
     ######################
 
-    stream: master
     branch: master
+    build-timeout: 10
+    stream: master
     submodule-recursive: true
 
+    gerrit_trigger_file_paths:
+      - compare-type: ANT
+        pattern: '**/*.sh'
+      - compare-type: ANT
+        pattern: '**/*.yaml'
+
     #####################
     # Job Configuration #
     #####################
 
+    project-type: freestyle
+    node: '{build-node}'
+
     properties:
       - lf-infra-properties:
           project: '{project}'
@@ -155,7 +154,7 @@
 
     wrappers:
       - lf-infra-wrappers:
-          build-timeout: 10
+          build-timeout: '{build-timeout}'
           jenkins-ssh-credential: '{jenkins-ssh-credential}'
 
     publishers:
@@ -165,27 +164,39 @@
 # JJB Merge #
 #############
 
-- lf_jjb_merge_builders: &lf_jjb_merge_builders
-    name: lf-jjb-merge-builders
-    builders:
-      - lf-infra-jjbini
-      - shell: !include-raw-escape:
-          - ../shell/jjb-install.sh
-          - ../shell/jjb-merge-job.sh
-
-- job-template:
-    name: '{project-name}-jjb-merge'
-    id: gerrit-jjb-merge
-    <<: *lf_jjb_common
-    # yamllint disable-line rule:key-duplicates
-    <<: *lf_jjb_merge_builders
+- lf_jjb_merge: &lf_jjb_merge
+    name: lf-jjb-merge
+
+    # JJB Merge job runs `jenkins-jobs update` to update production job configuration
+    #
+    # Required parameters:
+    #
+    #     :build-node: The node to run build on.
+    #     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
+    #         be configured in defaults.yaml)
+    #     :mvn-settings: The name of settings file containing credentials for
+    #         the project.
+    #
+    # Optional parameters:
+    #
+    #     :branch: Git branch to fetch for the build. (default: master)
+    #     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
+    #     :build-timeout: Timeout in seconds before aborting build. (default: 10)
+    #     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+    #     :stream: Keyword that can be used to represent a release code-name.
+    #         Often the same as the branch. (default: master)
+    #     :submodule-recursive: Whether to checkout submodules recursively.
+    #         (default: true)
+    #
+    #     :gerrit_merge_triggers: Override Gerrit Triggers.
+    #     :gerrit_trigger_file_paths: Override file paths which can be used to
+    #         filter which file modifications will trigger a build.
+    #         (default defined by lf_jjb_common)
 
     ######################
     # Default parameters #
     ######################
 
-    git-url: '$GIT_URL/$GERRIT_PROJECT'
-
     gerrit_merge_triggers:
       - change-merged-event
       - comment-added-contains-event:
@@ -195,6 +206,21 @@
     # Job Configuration #
     #####################
 
+    builders:
+      - lf-infra-jjbini
+      - shell: !include-raw-escape:
+          - ../shell/jjb-install.sh
+          - ../shell/jjb-merge-job.sh
+
+- job-template:
+    name: '{project-name}-jjb-merge'
+    id: gerrit-jjb-merge
+    <<: *lf_jjb_common
+    # yamllint disable-line rule:key-duplicates
+    <<: *lf_jjb_merge
+
+    git-url: '$GIT_URL/$GERRIT_PROJECT'
+
     scm:
       - lf-infra-gerrit-scm:
           git-url: '{git-url}'
@@ -214,18 +240,14 @@
               branches:
                 - branch-compare-type: ANT
                   branch-pattern: '**/{branch}'
-              <<: *lf_jjb_file_paths
+              file-paths: '{obj:gerrit_trigger_file_paths}'
 
 - job-template:
     name: '{project-name}-jjb-merge'
     id: github-jjb-merge
     <<: *lf_jjb_common
     # yamllint disable-line rule:key-duplicates
-    <<: *lf_jjb_merge_builders
-
-    #####################
-    # Job Configuration #
-    #####################
+    <<: *lf_jjb_merge
 
     properties:
       - github:
@@ -258,31 +280,39 @@
 # JJB Verify #
 ##############
 
-- lf_jjb_verify_builders: &lf_jjb_verify_builders
-    name: lf-jjb-verfy-builders
-    builders:
-      - lf-infra-jjbini
-      - shell: !include-raw-escape:
-          - ../shell/git-validate-jira-urls.sh
-          - ../shell/jjb-install.sh
-          - ../shell/jjb-verify-job.sh
-          - ../shell/jjb-check-unicode.sh
-      - lf-infra-gpg-verify-git-signature
-
-- job-template:
-    name: '{project-name}-jjb-verify'
-    id: gerrit-jjb-verify
-    concurrent: true
-    <<: *lf_jjb_common
-    # yamllint disable-line rule:key-duplicates
-    <<: *lf_jjb_verify_builders
+- lf_jjb_verify: &lf_jjb_verify
+    name: lf-jjb-verify
+
+    # JJB Verify job runs `jenkins-jobs test` to validate JJB syntax
+    #
+    # Required parameters:
+    #
+    #     :build-node: The node to run build on.
+    #     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
+    #         be configured in defaults.yaml)
+    #     :mvn-settings: The name of settings file containing credentials for
+    #         the project.
+    #
+    # Optional parameters:
+    #
+    #     :branch: Git branch to fetch for the build. (default: master)
+    #     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
+    #     :build-timeout: Timeout in seconds before aborting build. (default: 10)
+    #     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+    #     :stream: Keyword that can be used to represent a release code-name.
+    #         Often the same as the branch. (default: master)
+    #     :submodule-recursive: Whether to checkout submodules recursively.
+    #         (default: true)
+    #
+    #     :gerrit_verify_triggers: Override Gerrit Triggers.
+    #     :gerrit_trigger_file_paths: Override file paths which can be used to
+    #         filter which file modifications will trigger a build.
+    #         (default defined by lf_jjb_common)
 
     ######################
     # Default parameters #
     ######################
 
-    git-url: '$GIT_URL/$GERRIT_PROJECT'
-
     gerrit_verify_triggers:
       - patchset-created-event:
           exclude-drafts: false
@@ -296,6 +326,26 @@
     # Job Configuration #
     #####################
 
+    concurrent: true
+
+    builders:
+      - lf-infra-jjbini
+      - shell: !include-raw-escape:
+          - ../shell/git-validate-jira-urls.sh
+          - ../shell/jjb-install.sh
+          - ../shell/jjb-verify-job.sh
+          - ../shell/jjb-check-unicode.sh
+      - lf-infra-gpg-verify-git-signature
+
+- job-template:
+    name: '{project-name}-jjb-verify'
+    id: gerrit-jjb-verify
+    <<: *lf_jjb_common
+    # yamllint disable-line rule:key-duplicates
+    <<: *lf_jjb_verify
+
+    git-url: '$GIT_URL/$GERRIT_PROJECT'
+
     scm:
       - lf-infra-gerrit-scm:
           git-url: '{git-url}'
@@ -315,19 +365,14 @@
               branches:
                 - branch-compare-type: ANT
                   branch-pattern: '**/{branch}'
-              <<: *lf_jjb_file_paths
+              file-paths: '{obj:gerrit_trigger_file_paths}'
 
 - job-template:
     name: '{project-name}-jjb-verify'
     id: github-jjb-verify
-    concurrent: true
     <<: *lf_jjb_common
     # yamllint disable-line rule:key-duplicates
-    <<: *lf_jjb_verify_builders
-
-    #####################
-    # Job Configuration #
-    #####################
+    <<: *lf_jjb_verify
 
     properties:
       - github: