Continuous Integration

From Furcas Wiki

This how-to is for developers who want to push code changes to the Git repository. If you only want to check out and view the code and do not want to publish it again, you will not have to read this article. We use the continuous integration system Hudson and Maven for central builds and tests of our code. This requires developers to take additional actions.

Contents 1 Use Cases: Prepare your code 1.1 How to add a project 1.2 How to delete a project 1.3 How to change the bundle version 1.4 How to group projects in a parent folder 1.5 How to write a Test Case 1.6 How to exclude a Test Case 2 Use Cases: Use Continuous Integration 2.1 How the "master" branch is tested 2.2 How to let own branches build and test 2.3 How to set up Email notifications

Use Cases: Prepare your code

How to add a project

Every Java project needs its own Maven configuration file - the pom.xml - and a module-entry in its parent pom.xml (found in the parent directory).

The easiest way to get an example pom.xml is to copy it from another project in the same parent directory. Here is an outline of one xml file and what you have to change:

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" 
   xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <artifactId>DSLEngineering</artifactId> <!-- All three values have to be identical to the parent -->
    <groupId>com.sap.dsl</groupId>
    <version>0.0.1-SNAPSHOT</version>
  </parent>
  <groupId>com.sap.dsl</groupId>
  <artifactId>ProjectName</artifactId> <!-- The name has to be identical to the bundle name specified in the manifest -->
  <version>ProjectVersion</version> <!-- The version has to be identical to the bundle version specified in the manifest -->
  <packaging>Package</packaging>
</project>

You can choose between the following packaging types [1]

eclipse-plugin 

This packaging type corresponds to Eclipse Plug-in and Plug-in Fragment projects.

eclipse-test-plugin 

Maven projects typically have separate test source directories in the same project. The Eclipse convention, however, is to have a separate test bundle (often a fragment of the host/target plugin with the suffix ".tests"). Tycho introduces new eclipse-test-plugin packaging type to represent such projects. Build behavior is like regular Eclipse plugins, but these are treated as Eclipse Plug-in Tests.

eclipse-feature 

This packaging type corresponds to Eclipse Feature project.

eclipse-update-site 

This packaging type corresponds to Eclipse Update Site.

In the parent pom.xml add your new project to the module-section:

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" 
   xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  ...
  <modules>
    <module>com.sap.furcas.utils</module>
    ...
    <!-- Add the line here containing the folder name (sometimes different from the project name) -->
    <module>my.brand.new.project</module>
    ...
    <module>org.antlr</module>
  </modules>
</project>

How to delete a project

After you have deleted the project folder, you need to adjust the parent pom.xml which is found in the parent folder. Look for the modules-section and remove the project's folder name (sometimes the folder name differs from the project name).

<?xml version="1.0" encoding="UTF-8"?>
...
<modules>
  <module>com.sap.furcas.utils</module>
  ...
  <module>com.sap.tc.moin.globalmodellistener</module>
  <module>com.sap.tc.moin.tcs.mof.editor</module>
  ...
  <module>org.antlr</module>
</modules>

How to change the bundle version

Keep in mind that the bundle version (defined in the manifest) has to be identical to the version defined in the pom.xml. If you want to change it you will have to change both of them. If the version contains the word .qualified, please replace it with -SNAPSHOT in the pom.xml.

Example: 3.2.1.qualifier in the MANIFEST.MF becomes 3.2.1-SNAPSHOT in the pom.xml.

How to group projects in a parent folder

The easiest way to get an example pom.xml is to copy it from another folder that groups projects. Here is an outline of one xml file and what you have to change:

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" 
   xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>

  <!-- The first 3 elements have to be identical to the parent-section in the child's pom.xml -->
  <groupId>com.sap.dsl</groupId>
  <artifactId>GroupName</artifactId>  <!-- Pick a name here; for example the folder name -->
  <version>0.0.1-SNAPSHOT</version>
  <packaging>pom</packaging>

  <parent>
    <groupId>com.sap.dsl</groupId>
    <artifactId>root</artifactId>     <!-- Copy this value from the parent pom.xml -->
    <version>0.0.1-SNAPSHOT</version> <!-- Copy this value from the parent pom.xml -->
  </parent>

  <!-- List all the child folders here -->
  <modules>
    <module>com.sap.project1</module>
    <module>com.sap.project2</module>
    <module>com.sap.project3</module>
  </modules>
</project>

How to write a Test Case

Please be careful to name the java file correctly, otherwise it will not be tested. One of the following options is possible:

• Test*.java
• *Test.java
• *TestCase.java

If you urgently need to include more files to be tested you will have to do this in the project’s pom.xml:

TODO: EXAMPLE

How to exclude a Test Case

There are three ways to exclude a test if it will prevent Maven from building and testing the code successfully. A helper class that is accidentally identified as a test because of its name can be excluded in the project’s pom.xml (however, the easiest way is to rename it):

<?xml version="1.0" encoding="UTF-8"?>
<project 
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
  xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
  <modelVersion>4.0.0</modelVersion>
  <parent>
    ...
  </parent>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.sonatype.tycho</groupId>
        <artifactId>maven-osgi-test-plugin</artifactId>
        <configuration>
          <excludes>
            <exclude>**/MyExcludedTest.java</exclude> <!-- Add your test here -->
            <exclude>**/TestUtility*.java</exclude>   <!-- Wildcards are allowed to exclude more than one file -->
            <exclude>**/*$*.java</exclude>            <!-- Add this line if you have inner classes which you don't want to test -->
          </excludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Another way to ignore only single test methods or classes is the Ignore annotation of JUnit 4. Be careful to use it together with the Test annotation, otherwise the test is not recognized and a "No runnable methods found" exception is thrown.

JUnit 3 does not know Java annotations yet. It will run methods starting with test*, therefore the best way to ignore a test is to rename the method to (for example) ignoredtest* or failingtest*. If the entire class needs to be excluded, please rename the Java file or exclude it in the pom.xml as described above.

Use Cases: Use Continuous Integration

How the "master" branch is tested

The Hudson job for building and testing the master branch is checking periodically for changes at the github master branch and triggers itself. So after you pushed something to the github master branch it's not necessary to run the Hudson job manually.

After Hudson has finished, the developer will be notified by mail about the build result. Notifications can be Success, Failure, Still Failing and Fixed.

You can get further information about the build by following the link in your notification mail.

How to let own branches build and test

If you want to add a job for building and testing your own branches, you can do so by clicking the "New Job" Link on your Hudson home page[2]. Enter a new Job name, choose "Copy existing job" and type "CopyFrom". When you've finshed confirm with the OK button.

Now specify the branches you want to build under Source Code Management->Git->Branches to Build on the following page. Finally you have to enable your job. You can do so by first saving your job and then hit the Enable Button on the following Job-Status-Page

You will find an Eclipse-Update-Site for your branch after sucessfull builds under http://furcashudson.dhcp.wdf.sap.corp/${GIT_BRANCH}-site/ where ${GIT_BRANCH} is the branchname at Github.com (Note that the Update-Site for the master branch is available under http://furcashudson.dhcp.wdf.sap.corp/update-site/)

How to set up Email notifications

To setup email notifications go to your job and click "Configure". On the Configuration Site of your job we recommend to choose between E-mail notification and editable Email Notification (enabling both will send one email for each).

E-mail notification allows you to easyly set up an reciepiants list with the options to Send e-mail for every unstable build and Send separate e-mails to individuals who broke the build. The E-mail will be triggered when a build fails, becomes unstable or returns to stable.

Editable Email Notification allows a more advanced installation of Email Notifications. You can define a Global Recipient List, set Content Type to Plain Text or HTML E-mail and costomize the Default Subject as well as the Default Content.

For further configurations hit the Advanced Button under Content Token Reference. Now you can add Triggers for different buildresults and specify to whom Emails will be send for this trigger. If you want someone to be notified for a particular trigger who's not in the Global Recipient List, you can add a trigger specific recipient, subject and content list by clicking the expand link.