Update Gradle docs to use module replacement rather than dependency substitution

[xenoterracide]

Signed-off-by: Caleb Cushing xenoterracide@gmail.com

[xenoterracide]

I don't know if it's possible but the syntax is valid for both kotlin and groovy so if it's possible to say the block is both...

[wilkinsona]

This doesn't quite work as proposed due to this behaviour that's described in Gradle's docs:

Note that if only google-collections appears in the dependency graph (e.g. no guava) Gradle will not eagerly replace it with guava. Module replacement is an information that Gradle uses for resolving conflicts. If there is no conflict (e.g. only google-collections or only guava in the graph) the replacement information is not used.

To get it to work, an explicit dependency on spring-boot-starter-log4j2 must be declared as well as the replacement:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-log4j2'
    modules {
        module("org.springframework.boot:spring-boot-starter-logging") {
            replacedBy("org.springframework.boot:spring-boot-starter-log4j2", "Use Log4j2 instead of Logback")
        }
    }
}

This is one line shorter than what we currently document:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}
configurations.all {
    resolutionStrategy.dependencySubstitution.all { dependency ->
        if (dependency.requested instanceof ModuleComponentSelector && dependency.requested.module == 'spring-boot-starter-logging') {
            dependency.useTarget("org.springframework.boot:spring-boot-starter-log4j2:$dependency.requested.version", 'Use Log4j2 instead of Logback')
        }
    }
}

The currently documented approach has the advantage of applying the substitution to every configuration with a dependency on spring-boot-starter-logging. The replacement approach will only work in configuration where both spring-boot-starter-logging and spring-boot-starter-log4j2 are present where the former will then be replaced by the latter.

I'm in two minds now as to whether or not we should make this change. In some situations, a module replacement will be better while in others a dependency substitution is a better choice. The module replacement is slightly more concise and I find it easier to read, but it's also slightly less likely to produce the desired outcome in all configurations. Let's see what the rest of the team thinks.

[xenoterracide]

I'm going to wait for further feedback on acceptance before making requested changes, but thanks for alerting me ;)

[wilkinsona]

Thank you, @xenoterracide.