Development Guide

About Developing Jervis

This document outlines how I develop Jervis.

• I use vim to edit files but any text editor or IDE will do.
• groovyConsole is used to import and interactively play with Groovy classes. To launch it execute ./gradlew console. Herein called the Groovy console.
• Review the jervis-api documentation. jervis-api documentation is provided for each Maven Central release of Jervis.
• Each jervis-api documentation page provides a Sample Usage section which gives an example for how to import and interact with that class in the Groovy console.
• Jervis exceptions are intentionally written in Java due to a bug tracked by Jervis issue #82]#82. Exceptions should continue to be written in Java and not Groovy.

Other than the main Groovy and Java source code, this repository provides examples of Job DSL plugin scripts and Pipeline shared library scripts.

• Job DSL scripts - scripts available in jobs/ and resources/ directory.
• Pipeline global shared library scripts - scripts available in resources/ and vars/ directory.

Background: JDK and Groovy support

Jervis needs to support compiling across multiple versions of Groovy and support multiple versions of JVM. Mainly because Jenkins supports a wide array of these versions over time. This requirement allows Jervis to support a wide array of Jenkins versions.

Jervis 2.0+ supports OpenJDK 11 and OpenJDK 17. Jervis supports all stable versions of Groovy between Groovy 2.4.21 and Groovy 4.x.

Java Virtual Machine (JVM) versions supported by Jenkins.

Java Version	By Jenkins version	Recommended Jervis version
JDK 7	prior to Jenkins 2.54	Not supported
JDK 8 required	Jenkins 2.54+	Jervis 1.7
OpenJDK11 required	Jenkins 2.357+	Jervis 2.0+
OpenJDK17	Jenkins 2.346.1+	Jervis 2.0+

Groovy versions supported by Jenkins.

Embedded Groovy	By Jenkins version
Groovy 1.8.9	Jenkins 1.x
Groovy 2.4.6	Jenkins 2.0+
Groovy 2.4.8	Jenkins 2.47+
Groovy 2.4.11	Jenkins 2.61+
Groovy 2.4.21	Jenkins 2.326+

Jervis is regularly tested with Groovy 2.4.21 (and also Groovy 2.5, 3.0, and 4.0) on both OpenJDK11 and OpenJDK17.

Prerequisites

OpenJDK 11 is required. No other prerequisites are required. Gradle wrapper self bootstraps all necessary dependencies.

Build Jervis

Run unit tests and package up the library jars. This step will automatically assemble dependencies. Though, ./gradlew assemble can be used to only download dependencies and do nothing else.

./gradlew clean check Jar

To only run unit tests then simply run ./gradlew clean check. The version of Groovy used to build Jervis can be customized via the GROOVY_VERSION environment variable.

export GROOVY_VERSION='4.0.6'
./gradlew clean check Jar

Jervis supports building in all stable Groovy versions 2.4.21 and later.

Generate API documentation

Sometimes a local development copy of jervis-api documentation is desirable.

./gradlew -PtestGroovydoc=1 groovydoc

Open ./build/docs/groovydoc/index.html in a web browser to view the documentation. Different styled documentation will be generated depending on the version of Groovy defined in the GROOVY_VERSION environment variable.

Generate code coverage reports

Jervis code coverage is integrated with SonarQube. You do not need to have your own SonarQube service.

Jervis provides its own self contained SonarQube stack which can be provisioned via docker-compose. It also has instructions on how to generate code coverage reports.

Integrating with Jenkins

Jervis development can be built in Jenkins which is configured to use Jervis. Refer to the [.travis.yml file][travis-yml] which is the Jervis build script.

• Unit test reports are collected from ./build/test-results/*.xml.
• Build artifacts are collected from ./build/libs/*.jar.