README.md

   1 # How to test locally
   2 * Use the official Jenkins docker image:
   3     docker run -d -p 8080:8080 jenkins:weekly"
   4 * Then install the Jenkins Plugin Dependencies as listed below
   5 * Run JJB with:
   6     jenkins-jobs -l DEBUG --conf jenkins.ini update jjb
   7
   8 # Jenkins Plugin Dependencies
   9 * Email-ext Plugin
  10 * Gerrit Trigger Plugin
  11 * Git Plugin
  12 * Sonar Plugin
  13 * SSH-Agent Plugin
  14
  15 # Creating jobs from OpenDaylight templates
  16
  17 The ODL Releng project provides 3 job templates which can be used to
  18 define basic jobs.
  19
  20 Note: The templates below depend on a modified JJB version to add
  21       support for Config File Provider module in the Maven Project
  22       module for JJB. This custom version of JJB can be found at:
  23       https://github.com/zxiiro/jenkins-job-builder/tree/support-config-file-provider
  24
  25 ## Verify Job Template
  26
  27 The Verify job template creates a Gerrit Trigger job that will trigger
  28 when a new patch is submitted to Gerrit.
  29
  30 Verify jobs can be retriggered in Gerrit by leaving a comment that says
  31 **recheck**.
  32
  33 ## Merge Job Template
  34
  35 The Merge job template is similar to the Verify Job Template except it
  36 will trigger once a Gerrit patch is merged into the repo.
  37
  38 Merge jobs can be retriggered in Gerrit by leavning a comment that says
  39 **remerge**.
  40
  41 ## Daily Job Template
  42
  43 The Daily (or Nightly) Job Template creates a job which will run on a
  44 Daily basis and also Submits Sonar reports.
  45
  46
  47 ## Basic Job Configuration
  48
  49 To create jobs based on the above templates you can use the example
  50 template which will create 6 jobs (verify, merge, and daily jobs for both
  51 master and stable/helium branch).
  52
  53 Run the following steps from the repo root to create initial job config.
  54 This script will produce a file in jjb/<project>/<project>.yaml
  55 containing your project's base template.
  56
  57     python scripts/jjb-init-project.py <project-name>
  58
  59     # Example
  60     python scripts/jjb-init-project.py aaa
  61
  62     # Note: The optional options below require you to remove the 1st line
  63     #       comment in the produced template file otherwise the auto
  64     #       update script will overwrite the customization next time it
  65     #       is run. See Auto Update Job Templates section below for more
  66     #       details.
  67     #
  68     # Optionally pass the following options:
  69     #
  70     # -g / --mvn-goals      : With your job's Maven Goals necessary to build
  71     #                         (defaults to "clean install")
  72     #          Example      : -g "clean install"
  73     #
  74     # -o / --mvn-opts       : With your job's Maven Options necessary to build
  75     #                         (defaults to empty)
  76     #          Example      : -o "-Xmx1024m"
  77     #
  78     # -d / --dependencies   : A comma-seperated (no spaces) list of projects
  79     #                         your project depends on.
  80     #                         This is used to create an integration job that
  81     #                         will trigger when a dependent project-merge job
  82     #                         is built successfully.
  83     #          Example      : aaa,controller,yangtools
  84     #
  85     # -z / --no-cfg         : Do not auto-generate a project.cfg file if
  86     #                         -g, -o, -d parameters are passed. Usually
  87     #                         when these parameters are passed we will
  88     #                         assume customizations are made and create
  89     #                         the project file. (Useful in scripts like
  90     #                         the jjb-autoupdate-project.py script)
  91
  92 If all your project requires is the basic verify, merge, and
  93 daily jobs then using the job.template should be all you need to
  94 configure for your jobs.
  95
  96 ### Auto Update Job Templates
  97
  98 The first line of the job YAML file produced by the script will contain
  99 the words # REMOVE THIS LINE IF... leaving this line will allow the
 100 releng/builder autoupdate script to maintain this file for your project
 101 should the base template ever change. It is a good idea to leave this
 102 line if you do not plan to create any complex jobs outside of the
 103 provided template.
 104
 105 However if your project needs more control over your jobs or if you have
 106 any additional configuration outside of the standard configuration
 107 provided by the template then this line should be removed.
 108
 109 #### Tuning templates
 110
 111 Additionally the auto-updater does allow some small tweaks to the template
 112 so that you can take advantage of the template while at the same time
 113 tuning small aspects of your jobs. To take advantage of this simply create
 114 a file in your project's jjb directory called **project.cfg** with the
 115 following contents and tune as necessary. If there is a parameter you do
 116 NOT want to tune simply remove the parameter or comment out the line with a
 117 "#"" sign.
 118
 119     MVN_GOALS: clean install javadoc:aggregate -DrepoBuild -Dmaven.repo.local=$WORKSPACE/.m2repo -Dorg.ops4j.pax.url.mvn.localRepository=$WORKSPACE/.m2repo
 120     MVN_OPTS: -Xmx1024m -XX:MaxPermSize=256m
 121     DEPENDENCIES: aaa,controller,yangtools
 122
 123 #### Advanced
 124
 125 It is also possible to take advantage of both the auto updater and creating
 126 your own jobs. To do this, create a YAML file in your project's sub-directory
 127 with any name other than <project>.yaml. The auto-update script will only
 128 search for files with the name <project>.yaml. The normal <project>.yaml
 129 file can then be left in tact with the "# REMOVE THIS LINE IF..." comment so
 130 it will be automatically updated.