CONTRIBUTING.adoc

Contributors Guide

Table of Contents

• Local Environment
• Running Tests
  • Execute tests for a specific class
  • Code Coverage
• Linting
• Building the JPI
• Building the Documentation
  • Customizing the documentation output directory
• Publishing JTE
• Run a containerized Jenkins
  • Change the container name
  • Change the port forwarding target
  • Pass arbitrary flags to the container
  • Mounting local libraries for testing

Local Environment

Table 1. Tools

Tool	Purpose
Gradle	Used to run unit tests, package the JPI, and publish the plugin
Just	A task runner. Used here to automate common commands used during development.
Docker	Used to build the documentation for local preview

Running Tests

To run all the tests, run:

just test

The gradle test report is published to build/reports/tests/test/index.html

Execute tests for a specific class

To run tests for a specific Class, StepWrapperSpec for example, run:

just test '*.StepWrapperSpec'

Code Coverage

By default, JaCoCo code coverage is enabled when running test.

Once executed, the JaCoCo coverage report can be found at: build/reports/jacoco/test/html/index.html

To disable this, run:

just --set coverage false test

Linting

This project uses Spotless and CodeNarc to perform linting. The CodeNarc rule sets for src/main and src/test can be found in config/codenarc/rules.groovy and config/codenarc/rulesTest.groovy, respectively.

Once executed, the reports can be found at build/reports/codenarc/main.html and build/reports/codenarc/test.html.

To execute linting, run:

just lint

Building the JPI

To build the JPI, run:

just jpi

Once built, the JPI will be located at build/libs/templating-engine.jpi

Building the Documentation

This project uses Antora to build the documentation.

To build the documentation, run:

just docs

Once built, the documentation can be viewed at docs/html/index.html

Customizing the documentation output directory

The docsDir justfile variable configures the output directory.

To modify the output directory, run:

just --set docsDir some/other/directory docs

Publishing JTE

If you have the permission, you can cut a new release of JTE by running just release <versionNumber>.

For example:

just release 2.0.4

This will:

1. create a release/2.0.4 branch

2. update the version in the build.gradle

3. update the version in the docs/antora.yml

4. push those changes

5. create a 2.0.4 tag

6. publish the JPI

Note	Don’t forget to go to the Releases Page to officially release JTE with the current change log based off the most recent tag.

Run a containerized Jenkins

It is often helpful to run Jenkins in a container locally to test various scenarios with JTE during development.

just run

With the default settings, this will expose jenkins on http://localhost:8080

Change the container name

just --set container someName run

Change the port forwarding target

just --set port 9000 run

Pass arbitrary flags to the container

Parameters passed to just run are sent as flags to the docker run command.

just run -e SOMEVAR="some var"

Mounting local libraries for testing

Local directories can be configured as Git SCM library sources even if they do not have a remote repository.

For example, if ~/local-libraries is a directory containing a local git repository then to mount it to the container you would run:

just run -v ~/local-libraries:/local-libraries

You could then configure a library source using the file protocol to specify the repository location at file:///local-libraries

Tip	When using this technique, changes to the libraries must be committed to be found. In a separate terminal, run: just watch ~/local-libraries to automatically commit changes to the libraries.