rewrite jjb usage file 97/397/9
authorMatthewLi <matthew.lijun@huawei.com>
Tue, 21 Apr 2015 11:38:45 +0000 (19:38 +0800)
committerMatthewLi <matthew.lijun@huawei.com>
Tue, 21 Apr 2015 12:28:11 +0000 (20:28 +0800)
JIRA OCTO-36
Change-Id: I2a3884123c3930b646400fac2a1d8148a99c856b
Signed-off-by: MatthewLi <matthew.lijun@huawei.com>
docs/opnfv-jjb-usage.rst

index 77bb383..d293662 100644 (file)
-Creating/Configuring/Verifying Jenkins Jobs
+===========================================
+How to write and use JJB?
 ============================================
 
 ============================================
 
-Clone the repo::
- git clone ssh://YOU@gerrit.opnfv.org:29418/releng
+What is Jenkins Job Builder
+----------------------------
 
 
-make changes::
+Jenkins Job Builder(JJB) takes simple descriptions of Jenkins jobs in YAML format, and uses them to configure Jenkins jobs. JJB keeps your job descriptions in human readable format and job template system simplifies the configuration of Jenkins jobs. Upstream documentation is available at http://ci.openstack.org/jenkins-job-builder/.
 
 
- git commit -sv
- git review
- remote: Resolving deltas: 100% (3/3)
- remote: Processing changes: new: 1, refs: 1, done
- remote:
- remote: New Changes:
- remote:   https://gerrit.opnfv.org/gerrit/51
- remote:
- To ssh://agardner@gerrit.opnfv.org:29418/releng.git
-  * [new branch]      HEAD -> refs/publish/master
+How to Write/Use Jenkins Job Builder
+------------------------------------
 
 
-Follow the link to gerrit https://gerrit.opnfv.org/gerrit/51 in a few moments the verify job will have completed and you will see Verified +1 jenkins-ci in the gerrit ui.
+Job template is widely used in JJBs and makes the configuration of Jenkins jobs simple, if you need to define several jobs which are nearly identical, except perhaps in their names, SCP targets, etc., then you may use a job template to specify the particulars of the job, and then use a project to realize the job with appropriate variable substitution.
 
 
-If the changes pass the verify job https://build.opnfv.org/ci/view/builder/job/builder-verify-jjb/ The patch can be submitited by a committer.
+To illustrate how to configure Jenkins jobs by using job template, we can start with a simple example used in our OPNFV releng project octopus directory, which is just used to print "Hello world from Octopus", shown as below::
 
 
-Job Types
+ -job-template:
+    name: octopus-test
 
 
-* Verify Job
+    node: master
 
 
- * Trigger: **recheck** or **reverify**
+    project-type: freestyle
 
 
-* Merge Job
- * Trigger: **remerge**
+    logrotate:
+        daysToKeep: 30
+        numToKeep: 10
+        artifactDaysToKeep: -1
+        artifactNumToKeep: -1
 
 
-The verify and merge jobs are retriggerable in Gerrit by simply leaving a comment with one of the keywords listed above. This is useful in case you need to re-run one of those jobs in case if build issues or something changed with the environment.
+    builders:
+        - shell: |
+            echo "Hello world from octopus"
 
 
-You can add below persons as reviewers to your patch in order to get it reviewed and submitted.
+the value "-1" here means keep forever, you can add this job template into the project jobs to run in jenkins::
 
 
-* Ulrich Kleber (Ulrich.Kleber@huawei.com)
-* Fatih Degirmenci (fatih.degirmenci@ericsson.com)
-* Xinyu Zhao(Jerry) (zhaoxinyu@huawei.com)
+ - project:
+     name: octopus
+     jobs:
+         - 'octopus-test'
 
 
-Or just email a request for submission to opnfv-helpdesk@rt.linuxfoundation.org
+then this job works!
 
 
-The Current merge and verify jobs for jenkins job builder as pulled from the repo::
+Further, if you are a developer who wants to set up a job template to be used in jenkins, we should dive into much more, taking one job template in releng project used for octopus project, the 'octopus-daily-{stream}', as an example::
 
 
- - project:
-    name: builder-jobs
-    jobs:
-        - 'builder-verify-jjb'
-        - 'builder-merge'
+ -job-template:
+    name: 'octopus-daily-{stream}'
 
 
-    project: 'releng'
+    node: master
 
 
- - job-template:
-    name: builder-verify-jjb
+    # Job template for daily builders
+    #
+    # Required Variables:
+    #     stream:    branch with - in place of / (eg. stable)
+    #     branch:    branch (eg. stable)
 
     project-type: freestyle
 
     project-type: freestyle
+    varsetabove: '{somevar}'
 
     logrotate:
 
     logrotate:
-        daysToKeep: 30
-        numToKeep: 10
-        artifactDaysToKeep: -1
-        artifactNumToKeep: -1
+        daysToKeep: '{build-days-to-keep}'
+        numToKeep: '{build-num-to-keep}'
+        artifactDaysToKeep: '{build-artifact-days-to-keep}'
+        artifactNumToKeep: '{build-artifact-num-to-keep}'
 
     parameters:
         - project-parameter:
             project: '{project}'
 
     parameters:
         - project-parameter:
             project: '{project}'
-        - gerrit-parameter:
-            branch: 'master'
+
     scm:
     scm:
-        - gerrit-trigger-scm:
+        - git-scm:
             credentials-id: '{ssh-credentials}'
             credentials-id: '{ssh-credentials}'
-            refspec: '$GERRIT_REFSPEC'
-            choosing-strategy: 'gerrit'
+            refspec: ''
+            branch: '{branch}'
 
     wrappers:
         - ssh-agent-credentials:
             user: '{ssh-credentials}'
 
     triggers:
 
     wrappers:
         - ssh-agent-credentials:
             user: '{ssh-credentials}'
 
     triggers:
-        - gerrit:
-            trigger-on:
-                - patchset-created-event:
-                    exclude-drafts: 'false'
-                    exclude-trivial-rebase: 'false'
-                    exclude-no-code-change: 'false'
-                - draft-published-event
-                - comment-added-contains-event:
-                    comment-contains-value: 'recheck'
-                - comment-added-contains-event:
-                    comment-contains-value: 'reverify'
-            projects:
-              - project-compare-type: 'ANT'
-                project-pattern: 'releng'
-                branches:
-                  - branch-compare-type: 'ANT'
-                    branch-pattern: '**/master'
-                file-paths:
-                    - compare-type: ANT
-                      pattern: jjb/**
-                    - compare-type: ANT
-                      pattern: jjb-templates/**
+        - timed: 'H H * * *'
 
 
+    prebuilders:
+        - test-macro
 
     builders:
 
     builders:
-        - shell: |
-            source /opt/virtualenv/jenkins-job-builder/bin/activate
-            jenkins-jobs test /opt/jenkins-ci/builder/
+        - shell:
+            !include-raw build-upload-docu.sh
 
 
- job-template:
-    name: 'builder-merge'
   postbulders:
+        - test-macro
 
 
-    # builder-merge job to run JJB update
-    #
-    # This job's purpose is to update all the JJB
+the {stream} here means when you add this into jobs, you can replace {stream} with what you want, such as::
 
 
-    project-type: freestyle
+ stream:
+        - master:
+            branch: 'master'
 
 
-    logrotate:
-        daysToKeep: 30
-        numToKeep: 40
-        artifactDaysToKeep: -1
-        artifactNumToKeep: 5
+the::
 
 
-    parameters:
-        - project-parameter:
-            project: '{project}'
-        - gerrit-parameter:
-            branch: 'master'
+ node: master
 
 
-    scm:
-        - gerrit-trigger-scm:
-            credentials-id: '{ssh-credentials}'
-            refspec: ''
-            choosing-strategy: 'default'
+means to restrict this job to run in Jenkins master node. Next, several important procedures are illustrated here,
 
 
-    wrappers:
-        - ssh-agent-credentials:
-            user: '{ssh-credentials}'
+- scm, this mudule allows you to specify the source code location for the project, and it allows referencing multiple repositories in a Jenkins job.
+- triggers, this module defines what causes a Jenkins job to start building.
+- prebuilders and postbuilders, which define job need done pre and post the builders.
+- builders, which defines actions that the Jenkins job should execute, usually the shell scripts or maven targets are existed there, e.g., build-upload-docu.sh used in our example.
 
 
-    triggers:
-        - gerrit:
-            trigger-on:
-                - change-merged-event
-                - comment-added-contains-event:
-                    comment-contains-value: 'remerge'
-            projects:
-              - project-compare-type: 'ANT'
-                project-pattern: 'releng'
-                branches:
-                    - branch-compare-type: 'ANT'
-                      branch-pattern: '**/master'
-                file-paths:
-                    - compare-type: ANT
-                      pattern: jjb/**
+Generally, the modules used in a job template is sequenced as
 
 
-    builders:
-        - shell: |
-                source /opt/virtualenv/jenkins-job-builder/bin/activate
-                cd /opt/jenkins-ci/releng
-                git pull
-                jenkins-jobs update --delete-old jjb/
+1.parameters, properties
+2.scm
+3.triggers
+4.wrappers
+5.prebuilders
+6.builders
+7.postbuilders
+8.publishers, reporters, notifications
+
+Working with OPNFV Jenkins Jobs
+-------------------------------
+
+By now, the releng project of OPNFV is the release engineering project for JJBs, you can clone the repo::
+
+ git clone ssh://YOU@gerrit.opnfv.org:29418/releng
+
+make changes::
+
+ git commit -sv
+ git review
+ remote: Resolving deltas: 100% (3/3)
+ remote: Processing changes: new: 1, refs: 1, done
+ remote:
+ remote: New Changes:
+ remote:   https://gerrit.opnfv.org/gerrit/51
+ remote:
+ To ssh://agardner@gerrit.opnfv.org:29418/releng.git
+  * [new branch]      HEAD -> refs/publish/master
+
+Follow the link to gerrit https://gerrit.opnfv.org/gerrit/51 in a few moments the verify job will have completed and you will see Verified +1 jenkins-ci in the gerrit ui.
+
+If the changes pass the verify job https://build.opnfv.org/ci/view/builder/job/builder-verify-jjb/ The patch can be submitited by a committer.
+
+Job Types
+
+* Verify Job
+
+ * Trigger: **recheck** or **reverify**
+
+* Merge Job
+ * Trigger: **remerge**
+
+The verify and merge jobs are retriggerable in Gerrit by simply leaving a comment with one of the keywords listed above. This is useful in case you need to re-run one of those jobs in case if build issues or something changed with the environment.
+
+You can add below persons as reviewers to your patch in order to get it reviewed and submitted.
+
+* Ulrich Kleber (Ulrich.Kleber@huawei.com)
+* Fatih Degirmenci (fatih.degirmenci@ericsson.com)
+* Xinyu Zhao(Jerry) (zhaoxinyu@huawei.com)
+* Aric Gardner (agardner@linuxfoundation.org)
 
 
+The Current merge and verify jobs for jenkins job builder for releng project, shown in https://git.opnfv.org/cgit/releng/tree/jjb.
 
 
+Assuming that you have set up some job templates and put them into a project, then the question is that how they work? Taking the jobs 'builder-verify-jjb', 'builder-merge' used in releng project as examples, 'builder-verify-jjb' is to verify jobs you commited, you will see verified '+1' jenkins-ci in gerrit if it succeed, 'builder-merge' is to set up a merge job and update all the JJBs. If you have some new jobs need to be run, you can set up your own job templates and add them into the project.
 
 **Documentation tracking**
 
 
 **Documentation tracking**