Development Guide

Hello and thanks for taking your interest in contributing to the Jenkins Build Monitor Plugin!

This humble guide describes how to set up your development environment to build and test Jenkins Build Monitor Plugin. The guide is written with Linux/Unix/OsX-based workstations in mind, but it should be pretty straight-forward to build the project on Windows-running machines with some minor tweaks to pom.xml.

Build environment

Installing Dependencies

To execute a local build of this project you'll need to have following dependencies installed and available on your $PATH:

• Git - Github Guide to Installing Git is a good source of information
• Java JDK 7 - I use Oracle Java 7 64 bit with jenv on my Mac (Jenkins Core versions older than 1.612 and 1.625.1 LTS require Java 6), but the acceptance tests are written in Java 7
• Maven 3; I'm using 3.2.5 - http://maven.apache.org/
• Node.js and NPM; I'm using node.js v4.4.5 and npm 2.15.5 to run the JavaScript tests - http://nodejs.org/
• PhantomJS; I'm using 1.9.8 which you can get from http://phantomjs.org/, but it's possible to use other browsers as well. Read on :)
• Chrome - the acceptance tests run using Firefox so you'll need both the Chrome browser and the Chromedriver. If you're using Homebrew you can install chromedriver by running brew install chromedriver

Forking Build Monitor on Github

Once you have completed the above step you can go ahead and fork the Jenkins Build Monitor repository . You'll need a Github Account in case you don't have one already.

One-time Setup

Maven and access to Jenkins Plugins

Once you have Maven installed it may be helpful to add the following to your ~/.m2/settings.xml (Windows users will find them in %USERPROFILE%\.m2\settings.xml):

<settings>
  <pluginGroups>
    <pluginGroup>org.jenkins-ci.tools</pluginGroup>
  </pluginGroups>

  <profiles>
    <!-- Give access to Jenkins plugins -->
    <profile>
      <id>jenkins</id>
      <activation>
        <activeByDefault>true</activeByDefault> <!-- change this to false, if you don't like to have it on per default -->
      </activation>
      <repositories>
        <repository>
          <id>repo.jenkins-ci.org</id>
          <url>http://repo.jenkins-ci.org/public/</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>repo.jenkins-ci.org</id>
          <url>http://repo.jenkins-ci.org/public/</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <mirrors>
    <mirror>
      <id>repo.jenkins-ci.org</id>
      <url>http://repo.jenkins-ci.org/public/</url>
      <mirrorOf>m.g.o-public</mirrorOf>
    </mirror>
  </mirrors>

  <!-- other settings -->
</settings>

Project Workspace

With Maven set up you can move onto setting up the project workspace:

# Clone the Github repository, which you have forked in the previous step:
git clone git@github.com:<github username>/jenkins-build-monitor-plugin.git

# Go to the project workspace:
cd jenkins-build-monitor-plugin/build-monitor-plugin/

# Add the main Jenkins Build Monitor Plugin repository as an upstream remote to your clone:
git remote add upstream https://github.com/jan-molak/jenkins-build-monitor-plugin

# Install node.js dependencies:
npm install

# Test your setup:
mvn clean package

Building the Plugin

Got this far? Brilliant! Once you're done with setting up your environment, following commands will become available:

mvn clean test   
  - executes Java and JavaScript tests

mvn clean package
  - creates a *.hpi package that can be uploaded to a standalone Jenkins instance for testing purposes

mvn clean verify
  - executes end-to-end acceptance tests, deploying the *.hpi package to a Jenkins server that's downloaded, configured and managed for you by the mini test framework I wrote (it uses [Serenity BDD](http://serenity-bdd.info/docs/serenity/) under the hood)

npm test         
  - starts Karma server in auto-test mode, which means that JavaScript tests will be executed
    whenever any of the JavaScript files changes

Running a Local Development Server

You'll probably like to do some exploratory testing before submitting your pull request. This project comes with an embedded Jenkins server which you can start by issuing the following command:

./run
  - executes a shell script that starts an embedded Jenkins, so you can experiment with the plugin by navigating to
    http://localhost:8080/

Test-Driven Development

Backend

The backend is built in Java and has been test-driven using JUnit and a little DSL I wrote to make testing Jenkins plugins easier and less brittle.

If you'd like to extend the backend part of the plugin you'd probably like to start with familiarising yourself with the JUnit tests.

Frontend

The frontend is built in JavaScript and AngularJS and has been test-driven using Jasmine and Karma Runner.

If you'd like to use browsers other than PhantomJS to execute the JavaScript tests you can specify those in src/test/resources/karma.conf.js.

Commit messages

As you might have already noticed, I prefer to automate boring and repetitive tasks and leave them to computers. One of such tasks is writing release notes. Have a look at the release notes section of the Jenkins Build Monitor Plugin Wiki. Rather than writing up all the changes there I prefer to use my commit messages to tell the story.

In order to achieve this I found the following useful, and hope that you'll arrive at similar conclusion:

• use imperative, present tense do describe WHAT your change achieves, NOT HOW you've done it (everyone can see how you've done it in git history). For example:

  GOOD: "Defects in Stapler shouldn't break the Build Monitor"
  BAD:  "Using <st:bind var="..." value="..." /> rather than <st:bind value="..."/>"

Useful materials

• Jenkins Plugin Tutorial
• Writing a Hudson Plugin by Stephen Connolly
• Jelly Form Controls