Libyear Gradle Plugin

This Gradle plugin measures libyears of your project. libyears is a simple measure of software dependency freshness. It is a single number telling you how up-to-date your dependencies are. Learn more on libyear.com.

Usage

Update your Gradle build instructions with the following plugin application, which will automatically enable a dependency check after resolving dependencies:

// in Kotlin / build.gradle.kts:
plugins {
  id("com.libyear.libyear-gradle-plugin").version("<version>")
}

libyear {
   // Which dependency configuration to check?
  configurations = listOf("compileClasspath")
  
  // Fail in case fetching dependency metadata fails?
  failOnError = true

  // Sometimes fetching dependency metadata fails, so we retry a few times, after all retries fail, we throw an exception and "failOnError" policy will be applied.
  maxRetries: Int = 3
  initialRetryDelayMillis: Long = 2000
  retryBackoffMultiplier: Int = 2
  
  // How to validate:
  validator = allArtifactsCombinedMustNotBeOlderThan(5.years)
  
  // alternatively:
  validator = singleArtifactMustNotBeOlderThan(2.days)

  // optional: limit the depth of the dependency traversal, default is 0 = only the root level, null = no limit
  maxTransitiveDepth = 5
}

// in Groovy / build.gradle:
plugins {
  id 'com.libyear.libyear-gradle-plugin' version "<version>"
}

libyear {
  configurations = ['compileClasspath']
  failOnError = true
  validator = allArtifactsCombinedMustNotBeOlderThan(days(5))
  maxTransitiveDepth = 5
}

Please refer to LibYearExtension.kt for all possible configuration options and additional documentation.

Tasks

The reportLibyears task shows a table with all outdated dependencies, including their newest version numbers and impact on the total of libyears.

Example

If you build on a modern framework such as Spring Boot, you invite about 10 libyears into your project. And you haven't actually started to do something useful, did you?

> Task :example-spring-boot:reportLibyears
Collected 2.3 decades  worth of libyears from 33 dependencies:
 -> 4.2 years  from jakarta.annotation:jakarta.annotation-api (1.3.5 => 3.0.0-M1)
 -> 1.9 years  from org.slf4j:jul-to-slf4j (1.7.36 => 2.1.0-alpha0)
 -> 1.9 years  from org.slf4j:slf4j-api (1.7.36 => 2.1.0-alpha0)
 -> 1.8 years  from org.apache.logging.log4j:log4j-api (2.17.2 => 3.0.0-beta1)
 -> 1.8 years  from org.apache.logging.log4j:log4j-to-slf4j (2.17.2 => 3.0.0-beta1)
 -> 1.7 years  from org.yaml:snakeyaml (1.30 => 2.2)
 -> 11 months  from com.fasterxml.jackson.module:jackson-module-parameter-names (2.13.5 => 2.16.1)
 -> 11 months  from com.fasterxml.jackson.datatype:jackson-datatype-jdk8 (2.13.5 => 2.16.1)
 -> 11 months  from com.fasterxml.jackson.datatype:jackson-datatype-jsr310 (2.13.5 => 2.16.1)
 -> 11 months  from com.fasterxml.jackson.core:jackson-annotations (2.13.5 => 2.16.1)
 -> 11 months  from com.fasterxml.jackson:jackson-bom (2.13.5 => 2.16.1)
 -> 11 months  from com.fasterxml.jackson.core:jackson-core (2.13.5 => 2.16.1)
 -> 11 months  from com.fasterxml.jackson.core:jackson-databind (2.13.5 => 2.16.1)
 -> 8.3 months from ch.qos.logback:logback-core (1.2.12 => 1.4.14)
 -> 8.3 months from ch.qos.logback:logback-classic (1.2.12 => 1.4.14)
 -> 28.2 days  from org.springframework.boot:spring-boot-starter-tomcat (2.7.18 => 3.2.1)
 -> 28.2 days  from org.springframework.boot:spring-boot-starter-web (2.7.18 => 3.2.1)
 -> 28.2 days  from org.springframework.boot:spring-boot (2.7.18 => 3.2.1)
 -> 28.2 days  from org.springframework.boot:spring-boot-starter (2.7.18 => 3.2.1)
 -> 28.2 days  from org.springframework.boot:spring-boot-starter-json (2.7.18 => 3.2.1)
 -> 28.2 days  from org.springframework.boot:spring-boot-starter-logging (2.7.18 => 3.2.1)
 -> 28.2 days  from org.springframework.boot:spring-boot-autoconfigure (2.7.18 => 3.2.1)
 -> 28.1 days  from org.springframework:spring-aop (5.3.31 => 6.1.2)
 -> 28.1 days  from org.springframework:spring-context (5.3.31 => 6.1.2)
 -> 28.1 days  from org.springframework:spring-core (5.3.31 => 6.1.2)
 -> 28.1 days  from org.springframework:spring-expression (5.3.31 => 6.1.2)
 -> 28.1 days  from org.springframework:spring-web (5.3.31 => 6.1.2)
 -> 28.1 days  from org.springframework:spring-webmvc (5.3.31 => 6.1.2)
 -> 28.1 days  from org.springframework:spring-jcl (5.3.31 => 6.1.2)
 -> 28.1 days  from org.springframework:spring-beans (5.3.31 => 6.1.2)
 -> 27.7 days  from org.apache.tomcat.embed:tomcat-embed-websocket (9.0.83 => 11.0.0-M15)
 -> 27.7 days  from org.apache.tomcat.embed:tomcat-embed-el (9.0.83 => 11.0.0-M15)
 -> 27.7 days  from org.apache.tomcat.embed:tomcat-embed-core (9.0.83 => 11.0.0-M15)

BUILD SUCCESSFUL in 28s
1 actionable task: 1 executed

Changelog

0.4.0 (2025-04-08)

@Breefield kindly contributed retriable requests to the HTTP client to compensate for instability of upstream repositories. Fixes #16.

0.3.1 (2024-11-17)

We have merged two Dependabot PRs with GitHub Action version bumps for this patch release.

0.3.0 (2024-11-17)

Thanks to @Breefield the plugin now supports inclusion and exclusion filters on dependencies. By example,

• Exclusion patterns allow to exclude Libyears from a particular framework, for example Spring, and
• Inclusion patterns allow to "narrow down" on a particular set of dependencies, which allows to answer questions such as "how many Libyears do internal artifacts from 'com.mycompany' bring in?"

If build authors use both pattern in conjunction, the plugin narrows down the dependencies to the inclusion list, and then proceeds to filter out dependencies matching the exclusion pattern(s).

Patterns allow for globbing, for example, the pattern com.mycompany:* matches all artifacts with group name "com.mycompany", and com.mycompany:logging-* would match all artifact names starting with "logging".

0.2.1 (2024-11-08)

Thanks to @Breefield the plugin now writes a JSON report in build/reports which contains a machine-readable report of Libyears per dependency 🚀

0.2.0 (2024-10-16)

@Breefield added the maxTransitiveDepth toggle to put an upper bound to the depth of dependency traversal.
Starting with 0.2.0, because the application owners have most control over direct dependencies (depth = 0), the plugin only reports the Libyears of direct dependencies by default.
The full Libyear report is available with unlimited depth (maxTransitiveDepth = null), but will take the most time and resources to complete.

0.1.8 (2024-06-17)

The build of this release tests against the latest Gradle 7.x and 8.x release.

0.1.7 (2024-01-01)

The build of this release tests against the latest Gradle 7.x release.

0.1.6 (2022-02-09)

This release uses Gradle 6.9.2 as baseline for running the test suite and the plugin deployment.

0.1.5 (2022-02-09)

This release uses Gradle 6.9.1 as baseline for running the test suite and the plugin deployment.

0.1.4 (2021-06-24)

The violators report now excludes up-to-date dependencies which contribute zero seconds to the accumulated libyears.

The build runs against Gradle 6.9, Gradle 7.1, and Ktlint 10.1.0.

0.1.3 (2021-06-23)

The plugin now also considers repositories defined in the settings script (settings.gradle or settings.gradle.kts) in addition to the project's repositories depending on the repositories mode. Previously, the plugin processed only the project's repositories.

The build also runs against Gradle 7 in addition to Gradle 6.x to prevent regressions.

Acknowledgements

J. Cox, E. Bouwers, M. van Eekelen and J. Visser, Measuring Dependency Freshness in Software Systems. In Proceedings of the 37th International Conference on Software Engineering (ICSE 2015), May 2015