Jenkins - How to Maintain Continuous Integration for Saros

This page will tell you how we should maintain continuous integration for the Saros project.

Overview

Jenkins is our continuous integration system (Jenkins is a fork of the Hudson CI application). It has three main purposes:
  • Continuously build the Saros codebase to ensure the code contains no compile errors.
  • Carry out a number of tests for every new build of Saros to ensure expected behaviour has not been changed.
  • Automatically perform any needed deployments.

Projects

A project is the fundamental object used in Jenkins (NOTE: they are sometimes called jobs, and confusingly are referred to as jobs internally). Projects are constructed to automate various tasks and are very configurable. To create new projects or configure existing ones you need to login. There are various attributes of projects which are important to know when talking about them. You should familiarise yourself with them, either by browsing a Jenkins user guide, or looking through the configuration page of one of our existing projects.
All of our projects run automatically using build triggers. There is no need to initiate projects manually, unless you wish to force a project to execute prematurely.
Furthermore, you can chain projects together, thereby making project B run immediately after project A has completed. We use this capability to run the test projects every time the build projects finish.
FIXME: There are no "projects" in Jenkins. These are Jobs (and the are always called jobs). What do you mean with: confusingly are referred to as jobs internally ? A Job can be run => resulting in a build.
 
 

Builds (Jenkins object)

Every time a project is run, the information is stored in a build. You can get information about a particular build by going to a project's page and choosing one from the build history. This is useful when a job fails and you want to find out why. Console Output is especially useful.

 

Our Projects

Build (our project category)

We have the following build projects:
  • Create Doxy: Compiles the Doxygen documentation for the saros-project.org site.
    • Runs once per day at midnight.
      • Runs the Doxygen tool against a local mirror repository on the saros-build VM. The mirror is here: /home/build/saros-mirror/ and the customised Doxygen configuration file is here: /var/lib/jenkins/scripts/doxy/
      • Outputs HTML into a folder named html. This folder is zipped into doxygen.tar.gz.
  • Create GettingStarted : Compiles the docbook documentation for the saros-project.org site.
  • Saros: Compiles the Saros project.
    • Jenkins polls our main Git repository every hour. When it notices that the Git has been updated, the build is triggered.
      • The build starts an Ant project, which compiles Saros.
      • A selection of other commands are run too, like FindBugs and PMD source code analysis.
      • A number of other projects are started when this project completes.
      • Notification of problematic builds are sent to saros-devel.
  • Saros Statistic Server: Builds the statistics feature.
  • Saros Whiteboard: Builds the Whiteboard project similarly to the Saros project.
  • Saros Widget Gallery: Builds the Widget Gallery project similarly to the Saros project.
  • Saros-Developer-Guider-Gerrit: Trigger testing changes for the getting started documentation
  • Saros-Gerrit: Trigger testing changes to Saros.
  • Statisticserver-Gerrit: Trigger testing changes to the statisticserver.

Test

We have the following test projects:
  • Test Saros JUnit: Runs the JUnit test suite.
    • Runs after the Saros project.
      • Builds a Cobertura code coverage report of the test suite.
      • If a build is unstable, an email is sent to saros-devel.
  • Test Saros Testlink: TBC
  • Test STF: Runs the STF self test suite.
    • Runs once per day at midnight.
      • Builds a Cobertura code coverage report of the test suite.
      • If a build is unstable, an email is sent to saros-devel.
  • Test Saros STF: Runs the STF test suite for Saros.
    • Runs once per day at 6 A.M.
      • Builds a Cobertura code coverage report of the test suite.
      • If a build is unstable, an email is sent to saros-devel.

 

Deploy

We have the following deployment projects:
  • Deploy Doxy: Deploys the Doxygen documentation.
    • Runs after the Create Doxy project.
      • Takes the doxygen.tar.gz file and unzips it into /var/www/sarosDoc/. This is an Apache folder mapped to saros-build.imp.fu-berlin.de/sarosDoc.
  • Deploy GettingStarted : Deploy the getting started documentation
    • Runs after the Create Doxy job
      • Takes the html.tar.bz2, unpacks it, copies the pdf. The file will be available through saros-build.imp.fu-berlin.de/sarosGettingStarted

 

JUnit tests

Configuration

The configuration for running JUnit tests is in the build.xml file. Jenkins uses this and runs its own local copy of JUnit.
The JUnit Ant Task collects all Java classes that end with "*Test" and will execute them as a JUnit test case.
  • Test suite classes must contain the character sequence "TestSuite" and must not end with "Test"
  • Test classes must end with "Test"
 

Writing tests

JUnit test cases are stored in the test (test/junit for Saros) folder at the top-level of the trunk. They are organised into packages according to what they test. Every test class have to be created in the same package as the class it will test. E.g: src/de/fu_berlin/inf/dpp/accountManagement/XMPPAccount.java => test/junit/de/fu_berlin/inf/dpp/accountManagement/XMPPAccountTest.java
  • When you add a new test class, make sure that the TestSuite class for the package is updated with the name of the test class.
  • If you add a new package, include a TestSuite package and add its name to the AllTestsSuite.java.

 

Make sure your tests run well locally before committing them to the repo. They will then be included in the Jenkins test suite and run automatically from then on.

 

Future

Jenkins can be used to automate almost anything. Here are some ideas for future directions:
  • A nightly build: Configure a job to build the required Saros jar files once per day. When convenient, we could choose a build at will, test it and then release it as an official release.
  • A release project: Automate as much of the Release Process as possible.