Nebula Dependency Recommender

A Gradle plugin that allows you to leave off version numbers in your dependencies section and have versions recommended by several possible sources. The most familiar recommendation provider that is supported is the Maven BOM (i.e. Maven dependency management metadata). The plugin will control the versions of any dependencies that do not have a version specified.

Table of Contents

• Nebula Dependency Recommender
  • Usage
  • Dependency recommender configuration
  • Built-in recommendation providers
  • Producing a Maven BOM for use as a dependency recommendation source
  • Version selection rules
    • 1. Forced dependencies
    • 2. Direct dependencies with a version qualifier
    • 3. Dependency recommendations
    • 4. Transitive dependencies
  • Conflict resolution and transitive dependencies
  • Accessing recommended versions directly

1. Usage

Apply the nebula-dependency-recommender plugin:

buildscript {
    repositories { jcenter() }

    dependencies {
        classpath 'com.netflix.nebula:nebula-dependency-recommender:3.1.0'
    }
}

apply plugin: 'nebula.dependency-recommender'

2. Dependency recommender configuration

Dependency recommenders are the source of versions. If more than one recommender defines a recommended version for a module, the last recommender specified will win.

dependencyRecommendations {
   mavenBom module: 'netflix:platform:latest.release'
   propertiesFile uri: 'http://somewhere/extlib.properties', name: 'myprops'
}

dependencies {
   compile 'com.google.guava:guava' // no version, version is recommended
   compile 'commons-lang:commons-lang:2.6' // I know what I want, don't recommend
   compile project.recommend('commmons-logging:commons-logging', 'myprops') // source the recommendation from the provider named myprops'
}

3. Built-in recommendation providers

Several recommendation providers pack with the plugin. The file-based providers all a shared basic configuration that is described separately.

• File-based providers
  • Maven BOM
  • Properties file
  • Nebula dependency lock
• Map
• Custom

4. Producing a Maven BOM for use as a dependency recommendation source

Suppose you want to produce a BOM that contains a recommended version for commons-configuration.

buildscript {
    repositories { jcenter() }
    dependencies { classpath 'com.netflix.nebula:nebula-dependency-recommender:3.+' }
}

apply plugin: 'maven-publish'
apply plugin: 'nebula.dependency-recommender'

group = 'netflix'

configurations { compile }
repositories { jcenter() }

dependencies {
   compile 'commons-configuration:commons-configuration:1.6'
}

publishing {
	publications {
	    parent(MavenPublication) {
	        // the transitive closure of this configuration will be flattened and added to the dependency management section
	        bomGenerator.fromConfigurations { configurations.compile }

	        // alternative syntax when you want to explicitly add a dependency with no transitives
	        bomGenerator.withDependencies { 'manual:dep:1' }

		// the bom will be generated with dependency coordinates of netflix:module-parent:1
	        artifactId = 'module-parent'
	        version = 1

	        // further customization of the POM is allowed if desired
	        pom.withXml { asNode().appendNode('description', 'A demonstration of maven POM customization') }
	    }
	}
	repositories {
	    maven {
	       url "$buildDir/repo" // point this to your destination repository
	    }
	}
}

The resultant BOM would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <groupId>netflix</groupId>
  <artifactId>module-parent</artifactId>
  <version>1</version>
  <packaging>pom</packaging>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>commons-digester</groupId>
        <artifactId>commons-digester</artifactId>
        <version>1.8</version>
      </dependency>
      <dependency>
        <groupId>commons-logging</groupId>
        <artifactId>commons-logging</artifactId>
        <version>1.1.1</version>
      </dependency>
      <dependency>
        <groupId>commons-lang</groupId>
        <artifactId>commons-lang</artifactId>
        <version>2.4</version>
      </dependency>
      <dependency>
        <groupId>commons-configuration</groupId>
        <artifactId>commons-configuration</artifactId>
        <version>1.6</version>
      </dependency>
      <dependency>
        <groupId>commons-beanutils</groupId>
        <artifactId>commons-beanutils</artifactId>
        <version>1.7.0</version>
      </dependency>
      <dependency>
        <groupId>commons-collections</groupId>
        <artifactId>commons-collections</artifactId>
        <version>3.2.1</version>
      </dependency>
      <dependency>
        <groupId>commons-beanutils</groupId>
        <artifactId>commons-beanutils-core</artifactId>
        <version>1.8.0</version>
      </dependency>
      <dependency>
        <groupId>manual</groupId>
        <artifactId>dep</artifactId>
        <version>1</version>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <description>A demonstration of maven POM customization</description>
</project>

5. Version selection rules

The hierarchy of preference for versions is:

5.1. Forced dependencies

configurations.all {
    resolutionStrategy {
        force 'commons-logging:commons-logging:1.2'
    }
}

dependencyRecommendations {
   map recommendations: ['commons-logging:commons-logging': '1.1']
}

dependencies {
   compile 'commons-logging:commons-logging' // version 1.2 is selected
}

5.2. Direct dependencies with a version qualifier

Direct dependencies with a version qualifier trump recommendations, even if the version qualifier refers to an older version.

dependencyRecommendations {
   map recommendations: ['commons-logging:commons-logging': '1.2']
}

dependencies {
   compile 'commons-logging:commons-logging:1.0' // version 1.0 is selected
}

5.3. Dependency recommendations

This is the basic case described elsewhere in the documentation;

dependencyRecommendations {
   map recommendations: ['commons-logging:commons-logging': '1.0']
}

dependencies {
   compile 'commons-logging:commons-logging' // version 1.0 is selected
}

5.4. Transitive dependencies

Transitive dependencies interact with the plugin in different ways depending on which of two available strategies is selected.

5.4.1. OverrideTransitives Strategy (default)

In the following example version commons-logging:commons-logging:1.0 is selected even though commons-logging is not explicitly mentioned in dependencies. This would not work with the ConflictResolved strategy:

dependencyRecommendations {
   strategy OverrideTransitives // this is the default, so this line is NOT necessary
   map recommendations: ['commons-logging:commons-logging': '1.0']
}

dependencies {
   compile 'commons-configuration:commons-configuration:1.6'
}

5.4.2. ConflictResolved Strategy

Consider the following example with dependencies on commons-configuration and commons-logging. commons-configuration:1.6 depends on commons-logging:1.1.1. In this case, the transitive dependency on commons-logging via commons-configuration is conflict resolved against the recommended version of 1.0. Normal Gradle conflict resolution selects 1.1.1.

dependencyRecommendations {
   strategy ConflictResolved
   map recommendations: ['commons-logging:commons-logging': '1.0']
}

dependencies {
   compile 'commons-configuration:commons-configuration:1.6'
}

However, if we have a first-order recommendation eligible dependency on commons-logging, 1.0 will be selected.

dependencies {
   compile 'commons-configuration:commons-logging'
}

5.4.3. Bubbling up recommendations from transitives

If no recommendation can be found in the recommendation sources for a dependency that has no version, but a version is provided by a transitive, the version provided by the transitive is applied. In this scenario, if several transitives provide versions for the module, normal Gradle conflict resolution applies.

dependencyRecommendations {
   map recommendations: ['some:other-module': '1.1']
}

dependencies {
   compile 'commons-configuration:commons-configuration:1.6'
   compile 'commons-logging:commons-logging' // version 1.1.1 is selected
}

6. Conflict resolution and transitive dependencies

• Resolving differences between recommendation providers

7. Accessing recommended versions directly

The dependencyRecommendations container can be queried directly for a recommended version:

dependencyRecommendations.getRecommendedVersion('commons-logging', 'commons-logging')

The getRecommendedVersion method returns null if no recommendation is found.