New Project Quick Start
-----------------------
-.. note::
-
- We will be revamping releng/builder in the near future to simplify
- the below process.
-
This section attempts to provide details on how to get going as a new project
quickly with minimal steps. The rest of the guide should be read and understood
by those who need to create and contribute new job types that is not already
covered by the existing job templates provided by OpenDaylight's JJB repo.
As a new project you will be mainly interested in getting your jobs to appear
-in the jenkins-master_ silo and this can be achieved by simply creating 2 files
-project.cfg and project.yaml in the releng/builder project's jjb directory.
+in the jenkins-master_ silo and this can be achieved by simply creating a
+<project>.yaml in the releng/builder project's jjb directory.
.. code-block:: bash
- git clone https://git.opendaylight.org/gerrit/releng/builder
+ git clone --recursive https://git.opendaylight.org/gerrit/releng/builder
cd builder
mkdir jjb/<new-project>
+.. note:
+
+ releng/global-jjb is a submodule of releng/builder repository which
+ requires a git submodule update --init or using --recursive with git clone.
+ `releng-global-jjb`_
+
Where <new-project> should be the same name as your project's git repo in
-Gerrit. So if your project is called "aaa" then create a new jjb/aaa directory.
+Gerrit. If your project is called "aaa" then create a new jjb/aaa directory.
Next we will create <new-project>.yaml as follows:
- # REMOVE THIS LINE IF YOU WANT TO CUSTOMIZE ANYTHING BELOW
+.. code-block:: yaml
-That's right all you need is the above comment in this file. Jenkins will
-automatically regenerate this file when your patch is merged so we do not need
-to do anything special here.
+ ---
+ - project:
+ name: <NEW_PROJECT>-carbon
+ jobs:
+ - '{project-name}-clm-{stream}'
+ - '{project-name}-integration-{stream}'
+ - '{project-name}-merge-{stream}'
+ - '{project-name}-verify-{stream}-{maven}-{jdks}'
+
+ project: '<NEW_PROJECT>'
+ project-name: '<NEW_PROJECT>'
+ stream: carbon
+ branch: 'master'
+ jdk: openjdk8
+ jdks:
+ - openjdk8
+ maven:
+ - mvn33:
+ mvn-version: 'mvn33'
+ mvn-settings: '<NEW_PROJECT>-settings'
+ mvn-goals: 'clean install -Dmaven.repo.local=/tmp/r -Dorg.ops4j.pax.url.mvn.localRepository=/tmp/r'
+ mvn-opts: '-Xmx1024m -XX:MaxPermSize=256m'
+ dependencies: 'odlparent-merge-{stream},yangtools-merge-{stream},controller-merge-{stream}'
+ email-upstream: '[<NEW_PROJECT>] [odlparent] [yangtools] [controller]'
+ archive-artifacts: ''
+
+ - project:
+ name: <NEW_PROJECT>-sonar
+ jobs:
+ - '{project-name}-sonar'
+
+ project: '<NEW_PROJECT>'
+ project-name: '<NEW_PROJECT>'
+ branch: 'master'
+ mvn-settings: '<NEW_PROJECT>-settings'
+ mvn-goals: 'clean install -Dmaven.repo.local=/tmp/r -Dorg.ops4j.pax.url.mvn.localRepository=/tmp/r'
+ mvn-opts: '-Xmx1024m -XX:MaxPermSize=256m'
+
+Replace all instances of <new-project> with the name of your project. This will
+create the jobs with the default job types we recommend for Java projects. If
+your project is participating in the simultanious-release and ultimately will
+be included in the final distribution, it is required to add the following job
+types into the job list for the release you are participating.
-Next we will create <new-project>.cfg as follows:
.. code-block:: yaml
- STREAMS:
- - boron:
- branch: master
- jdks: openjdk8
- DEPENDENCIES: odlparent,controller,yangtools
+ - '{project-name}-distribution-check-{stream}'
+ - '{project-name}-validate-autorelease-{stream}'
-This is the minimal required CFG file contents and is used to auto-generate the
-YAML file. If you'd like to explore the additional tweaking options available
-please refer to the `Tuning Templates`_ section.
+If you'd like to explore the additional tweaking options available
+please refer to the `Jenkins Job Templates`_ section.
Finally we need to push these files to Gerrit for review by the releng/builder
team to push your jobs to Jenkins.
The Jenkins jobs are run on build minions (executors) which are created on an
as-needed basis. If no idle build minions are available a new VM is brought
up. This process can take up to 2 minutes. Once the build minion has finished a
-job, it will remain online for 45 minutes before shutting down. Subsequent
-jobs will use an idle build minion if available.
+job, it will be destroyed.
Our Jenkins master supports many types of dynamic build minions. If you are
creating custom jobs then you will need to have an idea of what type of minions
Adding New Components to the Minions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If your project needs something added to one of the minions used during build
-and test you can help us get things added faster by doing one of the following:
+If your project needs something added to one of the minions, you can help us
+get things added faster by doing one of the following:
-* Submit a patch to RelEng/Builder for the `spinup-scripts`_ that
- configures your new piece of software.
-* Submit a patch to RelEng/Builder for the Vagrant template's bootstrap.sh in
- the `vagrant-definitions`_ directory that configures your new piece of
- software.
+* Submit a patch to RelEng/Builder for the appropriate `jenkins-scripts`
+ definition which configure software during minion boot up.
+* Submit a patch to RelEng/Builder for the `packer/provision` scripts that
+ configures software during minion instance imaging.
+* Submit a patch to RelEng/Builder for the Packer's templates in
+ the `packer/templates` directory that configures a new instance definition
+ along with changes in `packer/provision`.
Going the first route will be faster in the short term as we can inspect the
changes and make test modifications in the sandbox to verify that it works.
-The second route, however, is better for the community as a whole as it will
-allow others that utilize our Vagrant setups to replicate our systems more
+.. note::
+
+ The first route may add additional setup time considering this is run every
+ time the minion is booted.
+
+The second and third routes, however, is better for the community as a whole as
+it will allow others to utilize our Packer setups to replicate our systems more
closely. It is, however, more time consuming as an image snapshot needs to be
-created based on the updated Vagrant definition before it can be attached to
-the sandbox for validation testing.
+created based on the updated Packer definitions before it can be attached to the
+Jenkins configuration on sandbox for validation testing.
In either case, the changes must be validated in the sandbox with tests to
make sure that we don't break current jobs and that the new software features
are operating as intended. Once this is done the changes will be merged and
-the updates applied to the RelEng Jenkins production silo.
-
-Please note that the combination of a Vagrant minion snapshot and a Jenkins
-spinup script is what defines a given minion. For instance, a minion may be
-defined by the `vagrant-basic-java-node`_ Vagrant definition
-and the `spinup-scripts-controller.sh`_ Jenkins spinup script
-(as the dynamic\_controller minion is). The pair provides the full definition of
-the realized minion. Jenkins starts a minion using the last-spun Vagrant snapshot
-for the specified definition. Once the base Vagrant instance is online Jenkins
-checks out the RelEng/Builder repo on it and executes two scripts. The first is
-`spinup-scripts-basic_settings.sh`_, which is a baseline for all of the minions.
-The second is
-the specialized spinup script, which handles any system updates, new software
-installs or extra environment tweaks that don't make sense in a snapshot. After
-all of these scripts have executed Jenkins will finally attach the minion as an
-actual minion and start handling jobs on it.
+the updates applied to the RelEng Jenkins production silo. Any changes to
+files under `releng/builder/packer` will be validated and images would be built
+triggered by verify-packer and merge-packer jobs.
+
+Please note that the combination of a Packer definitions from `vars`, `templates`
+and the `provision` scripts is what defines a given minion. For instance, a minion
+may be defined as `centos7-java-builder` which is a combination of Packer OS image
+definitions from `vars/centos.json`, Packer template definitions from
+`templates/java-buidler.json` and spinup scripts from `provision/java-builder.sh`.
+This combination provides the full definition of the realized minion.
+
+Jenkins starts a minion using the latest image which is built and linked into the
+Jenkins configuration. Once the base instance is online Jenkins checks out the
+RelEng/Builder repo on it and executes two scripts. The first is
+`provision/baseline.sh`, which is a baseline for all of the minions.
+
+The second is the specialized script, which handles any system updates,
+new software installs or extra environment tweaks that don't make sense in a
+snapshot. Examples could include installing new package or setting up a virtual
+environment. Its imperative to ensure modifications to these spinup scripts have
+considered time taken to install the packages, as this could increase the build
+time for every job which runs on the image. After all of these scripts have
+executed Jenkins will finally attach the minion as an actual minion and start
+handling jobs on it.
Pool: ODLRPC
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^
.. raw:: html
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> dynamic_verify</td>
- <td><b>Minion Template name</b><br/> centos7-builder</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-builder</td>
- <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/builder.sh</td>
+ <table class="table table-bordered">
+ <tr class="warning">
+ <td><b>Jenkins Labels</b><br/> centos7-java-builder-2c-4g,
+ centos7-java-builder-2c-8g, centos7-java-builder-4c-8g,
+ centos7-java-builder-8c-8g, centos7-java-builder-4c-16g</td>
+ <td><b>Minion Template names</b><br/> centos7-java-builder-2c-4g,
+ centos7-java-builder-2c-4g, centos7-java-builder-2c-8g,
+ centos7-java-builder-4c-8g, centos7-java-builder-8c-8g,
+ centos7-java-builder-4c-16g</td>
+ <td><b>Packer Template</b><br/>
+ releng/builder/packer/templates/java-builder.json</td>
+ <td><b>Spinup Script</b><br/>
+ releng/builder/jenkins-scripts/builder.sh</td>
</tr>
<tr>
<td colspan="4">
- A CentOS 7 huild minion. This system has OpenJDK 1.7 (Java7) and OpenJDK
- 1.8 (Java8) installed on it along with all the other components and
- libraries needed for building any current OpenDaylight project. This is
- the label that is used for all basic -verify and -daily- builds for
+ CentOS 7 build minion configured with OpenJDK 1.7 (Java7) and OpenJDK
+ 1.8 (Java8) along with all the other components and libraries needed
+ for building any current OpenDaylight project. This is the label that
+ is used for all basic verify, merge and daily builds for
projects.
</td>
</tr>
- </table>
-
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> dynamic_merge</td>
- <td><b>Minion Template name</b><br/> centos7-builder</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-builder</td>
- <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/builder.sh</td>
- </tr>
- <tr>
- <td colspan="4">
- See dynamic_verify (same image on the back side). This is the label that
- is used for all basic -merge and -integration- builds for projects.
- </td>
- </tr>
- </table>
-
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> matrix_master</td>
- <td><b>Minion Template name</b><br/> centos7-matrix</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-java-node</td>
- <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/matrix.sh</td>
- </tr>
- <tr>
- <td colspan="4">
- This is a very minimal system that is designed to spin up with 2 build
- instances on it. The purpose is to have a location that is not the
- Jenkins master itself for jobs that are executing matrix operations
- since they need a director location. This image should not be used for
- anything but tying matrix jobs before the matrx defined label ties.
- </td>
- </tr>
- </table>
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> dynamic_robot</td>
- <td><b>Minion Template name</b><br/> centos7-robot</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/integration-robotframework</td>
+ <tr class="warning">
+ <td><b>Jenkins Labels</b><br/> centos7-robot-2c-2g</td>
+ <td><b>Minion Template names</b><br/> centos7-robot-2c-2g</td>
+ <td><b>Packer Template</b><br/>
+ releng/builder/packer/templates/robot.json</td>
<td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/robot.sh</td>
</tr>
<tr>
<td colspan="4">
- A CentOS 7 minion that is configured with OpenJDK 1.7 (Java7), OpenJDK
+ CentOS 7 minion configured with OpenJDK 1.7 (Java7), OpenJDK
1.8 (Java8) and all the current packages used by the integration
project for doing robot driven jobs. If you are executing robot
framework jobs then your job should be using this as the minion that
building components of OpenDaylight, only for executing robot tests.
</td>
</tr>
- </table>
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> ubuntu_mininet</td>
- <td><b>Minion Template name</b><br/> ubuntu-trusty-mininet</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/ubuntu-mininet</td>
+ <tr class="warning">
+ <td><b>Jenkins Labels</b><br/> ubuntu1404-mininet-2c-2g</td>
+ <td><b>Minion Template names</b><br/> ubuntu1404-mininet-2c-2g</td>
+ <td><b>Packer Template</b><br/>
+ releng/builder/packer/teamplates/mininet.json</td>
<td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/mininet-ubuntu.sh</td>
</tr>
<tr>
<td colspan="4">
- Basic Ubuntu system with ovs 2.0.2 and mininet 2.1.0
+ Basic Ubuntu 14.04 (Trusty) system with ovs 2.0.2 and mininet 2.1.0
</td>
</tr>
- </table>
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> ubuntu_mininet_ovs_23</td>
- <td><b>Minion Template name</b><br/> ubuntu-trusty-mininet-ovs-23</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/ubuntu-mininet-ovs-23</td>
+ <tr class="warning">
+ <td><b>Jenkins Labels</b><br/> ubuntu1404-mininet-ovs-23-2c-2g</td>
+ <td><b>Minion Template names</b><br/> ubuntu1404-mininet-ovs-23-2c-2g</td>
+ <td><b>Packer Template</b><br/> releng/builder/packer/templates/mininet-ovs-2.3.json</td>
<td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/mininet-ubuntu.sh</td>
</tr>
<tr>
<td colspan="4">
- Basic Ubuntu system with ovs 2.3 and mininet 2.2.1
+ Ubuntu 16.04 (Xenial) system with ovs 2.5 and mininet 2.2.1
</td>
</tr>
- </table>
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> dynamic_controller</td>
- <td><b>Minion Template name</b><br/> centos7-java</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-java-node</td>
- <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/controller.sh</td>
- </tr>
- <tr>
- <td colspan="4">
- A CentOS 7 minion that has the basic OpenJDK 1.7 (Java7) and OpenJDK
- 1.8 (Java8) installed and is capable of running the controller, not
- building.
- </td>
- </tr>
- </table>
-
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> dynamic_java</td>
- <td><b>Minion Template name</b><br/> centos7-java</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-java-node</td>
- <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/controller.sh</td>
- </tr>
- <tr>
- <td colspan="4">
- See dynamic_controller as it is currently the same image.
- </td>
- </tr>
- </table>
-
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> dynamic_java_8g</td>
- <td><b>Minion Template name</b><br/> centos7-java-8g</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-java-node</td>
- <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/controller.sh</td>
- </tr>
- <tr>
- <td colspan="4">
- See dynamic_controller as it is currently the same image but with 8G of RAM.
- </td>
- </tr>
- </table>
-
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> dynamic_devstack</td>
- <td><b>Minion Template name</b><br/> centos7-devstack</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/ovsdb-devstack</td>
+ <tr class="warning">
+ <td><b>Jenkins Labels</b><br/> centos7-devstack-2c-4g</td>
+ <td><b>Minion Template names</b><br/> centos7-devstack-2c-4g</td>
+ <td><b>Packer Template</b><br/> releng/builder/packer/templates/devstack.json</td>
<td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/devstack.sh</td>
</tr>
<tr>
<td colspan="4">
- A CentOS 7 system purpose built for doing OpenStack testing using
+ CentOS 7 system purpose built for doing OpenStack testing using
DevStack. This minion is primarily targeted at the needs of the OVSDB
project. It has OpenJDK 1.7 (aka Java7) and OpenJDK 1.8 (Java8) and
other basic DevStack related bits installed.
</td>
</tr>
- </table>
- <table border="1">
- <tr>
- <td><b>Jenkins Label</b><br/> dynamic_docker</td>
- <td><b>Minion Template name</b><br/> centos7-docker</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/ovsdb-docker</td>
+ <tr class="warning">
+ <td><b>Jenkins Labels</b><br/> centos7-docker-2c-4g</td>
+ <td><b>Minion Template names</b><br/> centos7-docker-2c-4g</td>
+ <td><b>Packer Template</b><br/> releng/builder/packer/templates/docker.json</td>
<td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/docker.sh</td>
</tr>
<tr>
<td colspan="4">
- A CentOS 7 system that is configured with OpenJDK 1.7 (aka Java7),
+ CentOS 7 system configured with OpenJDK 1.7 (aka Java7),
OpenJDK 1.8 (Java8) and Docker. This system was originally custom
built for the test needs of the OVSDB project but other projects have
expressed interest in using it.
</td>
</tr>
- </table>
- <table border="1">
+ <tr class="warning">
+ <td><b>Jenkins Labels</b><br/> ubuntu1404-gbp-2c-2g</td>
+ <td><b>Minion Template names</b><br/> ubuntu1404-gbp-2c-2g</td>
+ <td><b>Packer Template</b><br/> releng/builder/packer/templates/gbp.json</td>
+ <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/ubuntu-docker-ovs.sh</td>
+ </tr>
<tr>
- <td><b>Jenkins Label</b><br/> gbp_trusty</td>
- <td><b>Minion Template name</b><br/> gbp_trusty</td>
- <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/gbp-ubuntu-docker-ovs-node</td>
+ <td colspan="4">
+ Ubuntu 14.04 (Trusty) node with latest OVS and docker installed. Used by Group Based Policy.
+ </td>
+ </tr>
+
+ <tr class="warning">
+ <td><b>Jenkins Labels</b><br/> ubuntu1604-gbp-2c-4g</td>
+ <td><b>Minion Template names</b><br/> ubuntu1604-gbp-2c-4g</td>
+ <td><b>Packer Template</b><br/> releng/builder/packer/templates/gbp.json</td>
<td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/ubuntu-docker-ovs.sh</td>
</tr>
<tr>
<td colspan="4">
- A basic Ubuntu node with latest OVS and docker installed. Used by Group Based Policy.
+ Ubuntu 16.04 (Xenial) node with latest OVS and docker installed. Used by Group Based Policy.
</td>
</tr>
+
</table>
+Pool: ODLPUB - HOT (Heat Orchestration Templates)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+HOT integration enables to spin up integration labs servers for CSIT jobs
+using heat, rathar than using jclouds (deprecated). Image names are updated
+on the project specific job templates using the variable
+`{odl,docker,openstack,tools}_system_image` followed by image name in the
+format `<platform> - <template> - <date-stamp>`.
+
+.. code-block:: yaml
+
+ CentOS 7 - docker - 20161031-0802
+
+.. include:: cloud-images.rst
+
Creating Jenkins Jobs
---------------------
their XML descriptions and upload them to the sandbox Jenkins server.
We document `installing <Installing Jenkins Job Builder_>`_ `jenkins-jobs`
-below. We also provide
-a `pre-built Docker image <jjb-docker_>`_ with `jenkins-jobs` already installed.
+below.
Installing Jenkins Job Builder
------------------------------
-For users who aren't already experienced with Docker or otherwise don't want
-to use our `pre-built JJB Docker image <jjb-docker_>`_, installing JJB into a
-virtual environment is an equally good option.
-
We recommend using `pip <Installing JJB using pip_>`_ to assist with JJB
installs, but we
also document `installing from a git repository manually
to manage JJB and its
Python dependencies. The `python-virtualenvwrapper`_ tool can help you do so.
-There are good docs for installing `python-virtualenvwrapper`_. On Linux systems
-with pip (typical), they amount to:
+Documentation is available for installing `python-virtualenvwrapper`_. On Linux
+systems with pip (typical), they amount to:
.. code-block:: bash
.. code-block:: bash
- $ git clone https://git.opendaylight.org/gerrit/p/releng/builder.git
+ $ git clone --recursive https://git.opendaylight.org/gerrit/p/releng/builder.git
Before actually installing JJB and its dependencies, make sure you've `created
and activated <Virtual Environments_>`_ a virtual environment for JJB.
(jjb)$ jenkins-jobs --version
+TODO: Explain that only the currently merged jjb/requirements.txt is supported,
+other options described below are for troubleshooting only.
+
To change the version of JJB specified by `builder/jjb/requirements.txt
<odl-jjb-requirements.txt_>`_
to install from the latest commit to the master branch of JJB's git repository:
(jjb)$ jenkins-jobs --version
-JJB Docker Image
-----------------
-
-`Docker <docker-docs_>`_ is an open platform used to create virtualized Linux containers
-for shipping self-contained applications. Docker leverages LinuX Containers
-\(LXC\) running on the same operating system as the host machine, whereas a
-traditional VM runs an operating system over the host.
-
-.. code-block:: bash
-
- docker pull zxiiro/jjb-docker
- docker run --rm -v ${PWD}:/jjb jjb-docker
-
-This `Dockerfile <jjb-dockerfile_>`_ created the
-`zxiiro/jjb-docker image <jjb-docker_>`_.
-By default it will run:
-
-.. code-block:: bash
-
- jenkins-jobs test .
-
-You'll need to use the `-v/--volume=[]` parameter to mount a directory
-containing your YAML files, as well as a configured `jenkins.ini` file if you
-wish to upload your jobs to the `Jenkins Sandbox`_.
Jenkins Job Templates
---------------------
The OpenDaylight `RelEng/Builder <releng-builder-wiki_>`_ project provides
`jjb-templates`_ that can be used to define basic jobs.
-Verify Job Template
-^^^^^^^^^^^^^^^^^^^
-
-Trigger: **recheck**
-
-The Verify job template creates a Gerrit Trigger job that will trigger when a
-new patch is submitted to Gerrit.
-
-Verify jobs can be retriggered in Gerrit by leaving a comment that says
-**recheck**.
-
-Merge Job Template
-^^^^^^^^^^^^^^^^^^
+The *Gerrit Trigger* listed in the jobs are keywords that can be used to
+trigger the job to run manually by simply leaving a comment in Gerrit for the
+patch you wish to trigger against.
-Trigger: **remerge**
+All jobs have a default build-timeout value of 360 minutes (6 hrs) but can be
+overrided via the opendaylight-infra-wrappers' build-timeout property.
-The Merge job template is similar to the Verify Job Template except it will
-trigger once a Gerrit patch is merged into the repo. It also automatically
-runs the Maven goals **source:jar** and **javadoc:jar**.
+TODO: Group jobs into categories: every-patch, after-merge, on-demand, etc.
+TODO: Reiterate that "remerge" triggers all every-patch jobs at once,
+because when only a subset of jobs is triggered, Gerrit forgets valid -1 from jobs outside the subset.
+TODO: Document that only drafts and commit-message-only edits do not trigger every-patch jobs.
+TODO: Document test-{project}-{feature} and test-{project}-all.
-This job will upload artifacts to `OpenDaylight's Nexus <odl-nexus_>`_ on completion.
-
-Merge jobs can be retriggered in Gerrit by leaving a comment that says
-**remerge**.
-
-Daily Job Template
-^^^^^^^^^^^^^^^^^^
-
-The Daily (or Nightly) Job Template creates a job which will run on a build on
-a Daily basis as a sanity check to ensure the build is still working day to
-day.
-
-Sonar Job Template
-^^^^^^^^^^^^^^^^^^
-
-Trigger: **run-sonar**
-
-This job runs Sonar analysis and reports the results to `OpenDaylight's Sonar
-dashboard <odl-sonar_>`_.
-
-The Sonar Job Template creates a job which will run against the master branch,
-or if BRANCHES are specified in the CFG file it will create a job for the
-**First** branch listed.
-
-.. note:: Running the "run-sonar" trigger will cause Jenkins to remove its
- existing vote if it's already -1'd or +1'd a comment. You will need to
- re-run your verify job (recheck) after running this to get Jenkins to
- re-vote.
-
-Integration Job Template
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Integration Job Template creates a job which runs when a project that your
-project depends on is successfully built. This job type is basically the same
-as a verify job except that it triggers from other Jenkins jobs instead of via
-Gerrit review updates. The dependencies that triger integration jobs are listed
-in your project.cfg file under the **DEPENDENCIES** variable.
-
-If no dependencies are listed then this job type is disabled by default.
-
-Distribution Test Job
-^^^^^^^^^^^^^^^^^^^^^
-
-Trigger: **test-distribution**
-
-This job builds a distrbution against your patch, passes distribution sanity test
-and reports back the results to Gerrit. Leave a comment with trigger keyword above
-to activate it for a particular patch.
-
-This job is maintained by the Integration/Test (`integration-test-wiki`_) project.
-
-.. note:: Running the "test-distribution" trigger will cause Jenkins to remove
- it's existing vote if it's already -1 or +1'd a comment. You will need
- to re-run your verify job (recheck) after running this to get Jenkins
- to put back the correct vote.
-
-Patch Test Job
-^^^^^^^^^^^^^^
-
-Trigger: **test-integration**
-
-This job runs a full integration test suite against your patch and reports
-back the results to Gerrit. Leave a comment with trigger keyword above to activate it
-for a particular patch.
-
-This job is maintained by the Integration/Test (`integration-test-wiki`_) project.
-
-.. note:: Running the "test-integration" trigger will cause Jenkins to remove
- it's existing vote if it's already -1 or +1'd a comment. You will need
- to re-run your verify job (recheck) after running this to get Jenkins
- to put back the correct vote.
-
-Some considerations when using this job:
-
-* The patch test verification takes some time (~2 hours) + consumes a lot of
- resources so it is not meant to be used for every patch.
-* The system tests for master patches will fail most of the times because both
- code and test are unstable during the release cycle (should be good by the
- end of the cycle).
-* Because of the above, patch test results typically have to be interpreted by
- system test experts. The Integration/Test (`integration-test-wiki`_) project
- can help with that.
-
-
-Autorelease Validate Job
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Trigger: **revalidate**
-
-This job runs the PROJECT-validate-autorelease-BRANCH job which is used as a
-quick sanity test to ensure that a patch does not depend on features that do
-not exist in the current release.
-
-The **revalidate** trigger is useful in cases where a project's verify job
-passed however validate failed due to infra problems or intermittent issues.
-It will retrigger just the validate-autorelease job.
-
-Python Verify Job
-^^^^^^^^^^^^^^^^^
-
-Trigger: **recheck** | **revalidate**
+.. raw:: html
-This job template can be used by a project that is Python based. It simply
-installs a python virtualenv and uses tox to run tests. When using the template
-you need to provide a {toxdir} which is the path relative to the root of the
-project repo containing the tox.ini file.
+ <table class="table table-bordered">
+ <tr class="warning">
+ <td><b>Job Template</b><br/>{project}-distribution-check-{stream}</td>
+ <td><b>Gerrit Trigger</b><br/>recheck</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ This job runs the PROJECT-distribution-check-BRANCH job which is
+ building also integration/distribution project in order to run SingleFeatureTest.
+ It also performs various other checks in order to prevent the change to break autorelease.
+ </td>
+ </tr>
-Node Verify Job
-^^^^^^^^^^^^^^^^^
+ <tr class="warning">
+ <td><b>Job Template</b><br/>{project}-integration-{stream}</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ The Integration Job Template creates a job which runs when a project that your
+ project depends on is successfully built. This job type is basically the same
+ as a verify job except that it triggers from other Jenkins jobs instead of via
+ Gerrit review updates. The dependencies that triger integration jobs are listed
+ in your project.cfg file under the <b>DEPENDENCIES</b> variable.
+
+ If no dependencies are listed then this job type is disabled by default.
+ </td>
+ </tr>
-Trigger: **recheck** | **revalidate**
+ <tr class="warning">
+ <td><b>Job Template</b><br/>{project}-merge-{stream}</td>
+ <td><b>Gerrit Trigger</b><br/>remerge</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ This job will trigger once a Gerrit patch is merged into the repo.
+ It will build HEAD of the current project branch and also run the Maven goals
+ <b>source:jar</b> and <b>javadoc:jar</b>.
+ Artifacts are uploaded to OpenDaylight's
+ <a href="https://nexus.opendaylight.org">Nexus</a> on completion.
+
+ A distribution-merge-{stream} job is triggered to add the new artifacts to the
+ integration distribution.
+
+ Running the "remerge" trigger is possible before a Change is merged,
+ it would still build the actual HEAD. This job does not alter Gerrit votes.
+ </td>
+ </tr>
-This job template can be used by a project that is NodeJS based. It simply
-installs a python virtualenv and uses that to install nodeenv which is then
-used to install another virtualenv for nodejs. It then calls **npm install**
-and **npm test** to run the unit tests. When using this template you need to
-provide a {nodedir} and {nodever} containing the directory relative to the
-project root containing the nodejs package.json and version of node you wish to
-run tests with.
+ <tr class="warning">
+ <td><b>Job Template</b><br/>{project}-sonar</td>
+ <td><b>Gerrit Trigger</b><br/>run-sonar</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ This job runs Sonar analysis and reports the results to
+ OpenDaylight's <a href="https://sonar.opendaylight.org">Sonar</a>
+ dashboard.
+
+ The Sonar Job Template creates a job which will run against the
+ master branch, or if BRANCHES are specified in the CFG file it will
+ create a job for the <b>First</b> branch listed.
+
+ <div class="admonition note">
+ <p class="first admonition-title">Note</p>
+ <p>
+ Running the "run-sonar" trigger will cause Jenkins to remove
+ its existing vote if it's already -1'd or +1'd a comment. You
+ will need to re-run your verify job (recheck) after running
+ this to get Jenkins to re-vote.
+ </p>
+ </div>
+ </td>
+ </tr>
-Basic Job Configuration
------------------------
+ <tr class="warning">
+ <td><b>Job Template</b><br/>{project}-validate-autorelease-{stream}</td>
+ <td><b>Gerrit Trigger</b><br/>recheck</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ This job runs the PROJECT-validate-autorelease-BRANCH job which is
+ used as a quick sanity test to ensure that a patch does not depend on
+ features that do not exist in the current release.
+ </td>
+ </tr>
-To create jobs based on existing `templates <Jenkins Job Templates_>`_, use the
-`jjb-init-project.py`_ helper script. When run from the root of
-`RelEng/Builder's repo <releng-builder-repo_>`_, it will produce a file in
-`jjb/<project>/<project>.yaml` containing your project's base template.
+ <tr class="warning">
+ <td><b>Job Template</b><br/>{project}-verify-{stream}-{maven}-{jdks}</td>
+ <td><b>Gerrit Trigger</b><br/>recheck</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ The Verify job template creates a Gerrit Trigger job that will
+ trigger when a new patch is submitted to Gerrit.
+ The job only builds the project code (including unit and integration tests).
+ </td>
+ </tr>
-.. code-block:: bash
+ <tr class="warning">
+ <td><b>Job Template</b><br/>{project}-verify-node-{stream}</td>
+ <td><b>Gerrit Trigger</b><br/>recheck</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ This job template can be used by a project that is NodeJS based. It
+ simply installs a python virtualenv and uses that to install nodeenv
+ which is then used to install another virtualenv for nodejs. It then
+ calls <b>npm install</b> and <b>npm test</b> to run the unit tests.
+ When using this template you need to provide a {nodedir} and
+ {nodever} containing the directory relative to the project root
+ containing the nodejs package.json and version of node you wish to
+ run tests with.
+ </td>
+ </tr>
- $ python scripts/jjb-init-project.py --help
- usage: jjb-init-project.py [-h] [-c CONF] [-d DEPENDENCIES] [-t TEMPLATES]
- [-s STREAMS] [-p POM] [-g MVN_GOALS] [-o MVN_OPTS]
- [-a ARCHIVE_ARTIFACTS]
- project
-
- positional arguments:
- project project
-
- optional arguments:
- -h, --help show this help message and exit
- -c CONF, --conf CONF Config file
- -d DEPENDENCIES, --dependencies DEPENDENCIES
- Project dependencies A comma-seperated (no spaces)
- list of projects your project depends on. This is used
- to create an integration job that will trigger when a
- dependent project-merge job is built successfully.
- Example: aaa,controller,yangtools
- -t TEMPLATES, --templates TEMPLATES
- Job templates to use
- -s STREAMS, --streams STREAMS
- Release streams to fill with default options
- -p POM, --pom POM Path to pom.xml to use in Maven build (Default:
- pom.xml
- -g MVN_GOALS, --mvn-goals MVN_GOALS
- Maven Goals
- -o MVN_OPTS, --mvn-opts MVN_OPTS
- Maven Options
- -a ARCHIVE_ARTIFACTS, --archive-artifacts ARCHIVE_ARTIFACTS
- Comma-seperated list of patterns of artifacts to
- archive on build completion. See:
- http://ant.apache.org/manual/Types/fileset.html
-
-If all your project requires is the basic verify, merge, and daily jobs then
-using the job template should be all you need to configure for your jobs.
-
-Auto-Update Job Templates
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The first line of the job YAML file produced by the `jjb-init-project.py`_ script will
-contain the words `# REMOVE THIS LINE IF...`. Leaving this line will allow the
-RelEng/Builder `jjb-autoupdate-project.py`_ script to maintain this file for your project,
-should the base templates ever change. It is a good idea to leave this line if
-you do not plan to create any complex jobs outside of the provided template.
-
-However, if your project needs more control over your jobs or if you have any
-additional configuration outside of the standard configuration provided by the
-template, then this line should be removed.
-
-Tuning Templates
-""""""""""""""""
-
-Allowing the auto-updated to manage your templates doesn't prevent you from
-doing some configuration changes. Parameters can be passed to templates via
-a `<project>.cfg` in your `builder/jjb/<project>` directory. An example is
-provided below, others can be found in the repos of other projects. Tune as
-necessary. Unnecessary paramaters can be removed or commented out with a "#"
-sign.
+ <tr class="warning">
+ <td><b>Job Template</b><br/>{project}-verify-python-{stream} | {project}-verify-tox-{stream}</td>
+ <td><b>Gerrit Trigger</b><br/>recheck</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ This job template can be used by a project that uses Tox to build. It
+ simply installs a Python virtualenv and uses tox to run the tests
+ defined in the project's tox.ini file. If the tox.ini is anywhere
+ other than the project's repo root, the path to its directory
+ relative to the project's repo root should be passed as {toxdir}.
+
+ The 2 template names verify-python & verify-tox are identical and are
+ aliases to each other. This allows the project to use the naming that
+ is most reasonable for them.
+ </td>
+ </tr>
-.. code-block:: yaml
+ <tr class="warning">
+ <td><b>Job Template</b><br/>integration-patch-test-{stream}</td>
+ <td><b>Gerrit Trigger</b><br/>test-integration</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ </td>
+ </tr>
- JOB_TEMPLATES: verify,merge,sonar
- STREAMS:
- - beryllium:
- branch: master
- jdks: openjdk7,openjdk8
- autorelease: true
- - stable-lithium:
- branch: stable/lithium
- jdks: openjdk7
- POM: dfapp/pom.xml
- MVN_GOALS: clean install javadoc:aggregate -DrepoBuild -Dmaven.repo.local=$WORKSPACE/.m2repo -Dorg.ops4j.pax.url.mvn.localRepository=$WORKSPACE/.m2repo
- MVN_OPTS: -Xmx1024m -XX:MaxPermSize=256m
- DEPENDENCIES: aaa,controller,yangtools
- ARCHIVE_ARTIFACTS: *.logs, *.patches
-
-.. note:: `STREAMS <streams-design-background_>`_ is a list of branches you want
- JJB to generate jobs for.
- The first branch will be the branch that reports Sonar analysis. Each
- branch must define a "jdks:" section listing the JDKs the verify jobs
- should run tests against for the branch. The first JDK listed will be
- used as the default JDK for non-verify type jobs.
-
-.. note:: Projects that are participating in the simultanious release should set
- "autorelease: true" under the streams they are participating in
- autorelease for. This enables a new job type validate-autorelease
- which is used to help identify if Gerrit patches might break
- autorelease or not.
-
-Advanced
-""""""""
-
-It is also possible to take advantage of both the auto-updater and creating
-your own jobs. To do this, create a YAML file in your project's sub-directory
-with any name other than \<project\>.yaml. The auto-update script will only
-search for files with the name \<project\>.yaml. The normal \<project\>.yaml
-file can then be left in tact with the "# REMOVE THIS LINE IF..." comment so
-it will be automatically updated.
+ <tr class="warning">
+ <td><b>Job Template</b><br/>integration-patch-test-{stream}</td>
+ <td><b>Gerrit Trigger</b><br/>test-integration</td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ This job builds a distribution against your Java patch and triggers distribution sanity CSIT jobs.
+ Leave a comment with trigger keyword above to activate it for a particular patch.
+ This job should not alter Gerrit votes for a given patch.
+
+ The list of CSIT jobs to trigger is defined in csit-list
+ <a href="https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jjb/integration/integration-test-jobs.yaml">here</a>.
+
+ Some considerations when using this job:
+ <ul>
+ <li>
+ The patch test verification takes some time (~2 hours) + consumes a lot of
+ resources so it is not meant to be used for every patch.
+ </li>
+ <li>
+ The system tests for master patches will fail most of the times because both
+ code and test are unstable during the release cycle (should be good by the
+ end of the cycle).
+ </li>
+ <li>
+ Because of the above, patch test results typically have to be interpreted by
+ system test experts. The <a href="https://wiki.opendaylight.org/view/Integration/Test">Integration/Test</a>
+ project can help with that.
+ </li>
+ </td>
+ </tr>
+ </table>
Maven Properties
----------------
.. code-block:: bash
# If you don't have RelEng/Builder's repo, clone it
- $ git clone https://git.opendaylight.org/gerrit/p/releng/builder.git
+ $ git clone --recursive https://git.opendaylight.org/gerrit/p/releng/builder.git
# Make a copy of the example JJB config file (in the builder/ directory)
$ cp jenkins.ini.example jenkins.ini
# Edit jenkins.ini with your username, API token and ODL's sandbox URL
Make changes to your JJB configuration, re-test, re-push and re-run until
your job is ready.
-Docker Method
-^^^^^^^^^^^^^
-
-If `using Docker <JJB Docker image_>`_:
-
-.. code-block:: bash
-
- # To test
- docker run --rm -v ${PWD}:/jjb zxiiro/jjb-docker
-
-.. important::
-
- When pushing with `jenkins-jobs`, a log message with
- the number of jobs you're pushing will be issued, typically to stdout.
- **If the number is greater than 1** (or the number of jobs you passed to
- the command to push) then you are pushing too many jobs and should **`ctrl+c`
- to cancel the upload**. Else you will flood the system with jobs.
-
- .. code-block:: bash
-
- INFO:jenkins_jobs.builder:Number of jobs generated: 1
-
- **Failing to provide the final `<job-name>` param will push all jobs!**
-
- .. code-block:: bash
-
- # To upload jobs to the sandbox
- # Please ensure that you include a configured jenkins.ini in your volume mount
- # Making sure not to push more jobs than expected, ctrl+c to abort
- docker run --rm -v ${PWD}:/jjb zxiiro/jjb-docker jenkins-jobs --conf jenkins.ini update . openflowplugin-csit-periodic-1node-cds-longevity-only-master
-.. _docker-docs: https://www.docker.com/whatisdocker/
.. _example-jenkins.ini: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jenkins.ini.example
.. _integration-test-wiki: https://wiki.opendaylight.org/view/Integration/Test
.. _jenkins-master: https://jenkins.opendaylight.org/releng
.. _jenkins-sandbox-login: https://jenkins.opendaylight.org/sandbox/login
.. _jenkins.ini: http://docs.openstack.org/infra/jenkins-job-builder/execution.html#configuration-file
.. _jjb-autoupdate-project.py: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=scripts/jjb-autoupdate-project.py
-.. _jjb-docker: https://hub.docker.com/r/zxiiro/jjb-docker/
-.. _jjb-dockerfile: https://github.com/zxiiro/jjb-docker/blob/master/Dockerfile
.. _jjb-docs: http://ci.openstack.org/jenkins-job-builder/
.. _jjb-init-project.py: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=scripts/jjb-init-project.py
.. _jjb-repo: https://github.com/openstack-infra/jenkins-job-builder
.. _releng-wiki: https://wiki.opendaylight.org/view/RelEng:Main
.. _releng-builder-gerrit: https://git.opendaylight.org/gerrit/#/admin/projects/releng/builder
.. _releng-builder-repo: https://git.opendaylight.org/gerrit/gitweb?p=releng%2Fbuilder.git;a=summary
+.. _releng-global-jjb: https://gerrit.linuxfoundation.org/infra/#/q/project:releng/global-jjb
.. _releng-builder-wiki: https://wiki.opendaylight.org/view/RelEng/Builder
.. _streams-design-background: https://lists.opendaylight.org/pipermail/release/2015-July/003139.html
.. _spinup-scripts: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=tree;f=jenkins-scripts
.. _spinup-scripts-basic_settings.sh: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jenkins-scripts/basic_settings.sh
.. _spinup-scripts-controller.sh: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jenkins-scripts/controller.sh
-.. _vagrant-basic-java-node: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=tree;f=vagrant/basic-java-node
-.. _vagrant-definitions: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=tree;f=vagrant
Code Review / releng / builder.git / blobdiff