This page will tell you how we should maintain continuous integration for the Saros project.
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.
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.
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 dpp-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.
We have the following test projects:
We have the following deployment projects:
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.
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.
Jenkins can be used to automate almost anything. Here are some ideas for future directions: