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.
To execute a local build of this project you'll need to have following dependencies installed and available on your
- 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/
- 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
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
<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>
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 firstname.lastname@example.org:<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:
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/
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.
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="..."/>"