Clirr Gradle Plugin

The clirr-gradle-plugin enables the usage of Clirr to calculate the binary compatibility between 2 releases.

Usage

Apply the org.kordamp.gradle.clirr plugin to your Gradle plugin project.

Gradle 1.x and 2.0

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'org.kordamp.gradle:clirr-gradle-plugin:0.2.4'
    }
}

apply plugin: 'org.kordamp.gradle.clirr'

Gradle 2.1 and higher

plugins {
    id 'org.kordamp.gradle.clirr' version '0.2.4'
}

Tasks

The org.kordamp.gradle.clirr plugin pre-defines the following tasks out-of-the-box:

Task Name	Depends On	Type	Description
clirr	-	org.kordamp.gradle.clirr.ClirrTask	Calculates the binary compatibility of the current codebase against a previous release

It’s likely that the clirr-gradle-plugin plugin is applied to multiple subprojects. Use the following task definition in order to generate an aggregate clirr report

build.gradle

task clirrRootReport(type: org.kordamp.gradle.clirr.ClirrReportTask) {
    dependsOn = subprojects.tasks.clirr
    reports = files((subprojects.findAll { it.clirr.enabled == true }).tasks.clirr.xmlReport)
}

Task Properties

The clirr task relies on the following properties specified in the clirr extension block

Property	Type	Default	Description
enabled	boolean	true	Controls whether the clirr task should be enabled or disabled
baseline	Object		Defines the previous release. Use standard dependency notation, e.g, "com.acme:foo:1.2.3"
semver	boolean	true	Evaluates the project’s version using semver rules
reportsDir	File	build/reports/clirr	Directory where reports will be written to
excludeFilter	File		A YAML file containing exclusions
failOnErrors	boolean	true	Abort the build if a compatibility issue with severity "error" is found
failOnException	boolean	false	Abort the build if Clirr triggers an Exception during its checks

The excludeFilter YAML file can define the following parameters

differenceTypes	A list of severity ids, e.g, [6000, 7011]
packages	A list of package names.
classes	A list of fully qualified classname.
members	A map of classname/memberName.

Packages may be excluded recursively if the .* char sequence is found at the end of the package name.

Additionally, the org.kordamp.gradle.clirr.ClirrReportTask accepts the following properties

Property	Type	Default	Description
reportsDir	File	build/reports/clirr	Directory where reports will be written to
filter	Closure		Excludes a compatibility issue if there’s a matching criteria.

The closure must take a single argument, which exposes the following properties

severity; java.lang.String; info, warning, error.
identifier; java.lang.String; severity id number.
classname; java.lang.String; fully qualified classname.
message; java.lang.String; formatted severity message.

You may skip defining a value for baseline and let the clirr figure out the the previous version according to the following rules

remove trailing tag if it exists
if the semver property is set to true (default)
1. if the minor version is 0 then revision is checked
  1. if revision is 0 clirr is disabled.
  2. if revision is > 0 decrement revision by 1.
2. if the minor version is > 0 then revision is checked
  1. if revision is 0 decrement minor by 1.
  2. if revision is > 0 decrement revision by 1.
if the semver property is set to false
if revision is 0 then clirr is disabled.
if revision is > 0 then revision is decremented by 1.

These rules produce the following outcomes given these inputs

semver = true

2.0.0 => disabled
2.0.4 => 2.0.3
2.1.0 => 2.0.0
2.1.3 => 2.1.2

semver = false

2.0.0 => disabled
2.0.4 => 2.0.3
2.1.0 => disabled
2.1.3 => 2.1.2

Example

The following example, taken from the Griffon build, calculates the clirr report of every submodule