README.md

@@ -449,6 +449,16 @@ The configurable fields of the `javaVersions` extension are:
 
 The configured Java versions are used as defaults for all projects.
 
+You can run the `explainJavaVersions` task to both show what the `target` and `runtime` versions are for each subproject, and explain why:
+
+```
+$ ./gradle explainJavaVersions
+> Task :subproject:explainJavaVersions
+target  = 11
+runtime = 17
+Reason: considered a distribution because it doesn't have any publishing extensions defined
+```
+
 If a sub-project should use `libraryTarget` but is not considered a library (for example, because it is not published), you can explicitly indicate that it is a library:
 
 ```gradle

build.gradle

@@ -11,12 +11,12 @@ buildscript {
         classpath 'com.diffplug.gradle:goomph:3.32.1'
         classpath 'com.palantir.gradle.externalpublish:gradle-external-publish-plugin:1.19.0'
         classpath 'com.palantir.gradle.failure-reports:gradle-failure-reports:1.13.0'
-        classpath 'com.palantir.gradle.consistentversions:gradle-consistent-versions:2.31.0'
+        classpath 'com.palantir.gradle.consistentversions:gradle-consistent-versions:2.32.0'
         classpath 'com.palantir.gradle.plugintesting:gradle-plugin-testing:0.6.0'
         classpath 'com.gradle.publish:plugin-publish-plugin:1.3.1'
         classpath 'com.palantir.baseline:gradle-baseline-java:6.16.0'
-        classpath 'com.palantir.javaformat:gradle-palantir-java-format:2.58.0'
-        classpath 'com.palantir.suppressible-error-prone:gradle-suppressible-error-prone:2.5.0'
+        classpath 'com.palantir.javaformat:gradle-palantir-java-format:2.61.0'
+        classpath 'com.palantir.suppressible-error-prone:gradle-suppressible-error-prone:2.7.0'
     }
 }
 

changelog/6.22.0/pr-3079.v2.yml

@@ -0,0 +1,7 @@
+type: improvement
+improvement:
+  description: 'baseline-java-versions: Provide an `explainJavaVersions` task that
+    makes it easier to work out which `target` and `runtime` java versions have been
+    chosen by the plugin and why.'
+  links:
+  - https://github.com/palantir/gradle-baseline/pull/3079

gradle-baseline-java/src/main/java/com/palantir/baseline/plugins/javaversions/BaselineJavaVersions.java

@@ -59,59 +59,82 @@ public void apply(Project project) {
                 proj.getExtensions().create(EXTENSION_NAME, SubprojectBaselineJavaVersionsExtension.class, proj));
 
         project.allprojects(proj -> proj.getPluginManager().withPlugin("java", unused -> {
-            proj.getPluginManager().apply(BaselineJavaVersion.class);
-            BaselineJavaVersionExtension projectVersions =
-                    proj.getExtensions().getByType(BaselineJavaVersionExtension.class);
+            configureJavaProject(proj, rootExtension);
+        }));
+    }
 
-            Provider<ChosenJavaVersion> suggestedTarget = proj.provider(() -> isLibrary(proj, projectVersions)
-                    ? ChosenJavaVersion.of(rootExtension.libraryTarget().get())
-                    : rootExtension.distributionTarget().get());
+    private static void configureJavaProject(Project project, BaselineJavaVersionsExtension rootExtension) {
+        project.getPluginManager().apply(BaselineJavaVersion.class);
+        BaselineJavaVersionExtension projectVersions =
+                project.getExtensions().getByType(BaselineJavaVersionExtension.class);
 
-            projectVersions.target().convention(suggestedTarget);
-            projectVersions.runtime().convention(rootExtension.runtime());
-        }));
+        Provider<ChosenJavaVersion> suggestedTarget = project.provider(() -> {
+            IsLibraryWithReason isLibraryWithReason = isLibrary(project, projectVersions);
+            log.info("{} is {}", project.getDisplayName(), isLibraryWithReason);
+            return isLibraryWithReason.isLibrary()
+                    ? ChosenJavaVersion.of(rootExtension.libraryTarget().get())
+                    : rootExtension.distributionTarget().get();
+        });
+
+        Property<ChosenJavaVersion> suggestedRuntime = rootExtension.runtime();
+
+        projectVersions.target().convention(suggestedTarget);
+        projectVersions.runtime().convention(suggestedRuntime);
+
+        project.getTasks().register("explainJavaVersions", ExplainJavaVersions.class, explainJavaVersions -> {
+            explainJavaVersions.getTarget().set(projectVersions.target());
+            explainJavaVersions.getDefaultTarget().set(suggestedTarget);
+            explainJavaVersions.getRuntime().set(projectVersions.runtime());
+            explainJavaVersions.getDefaultRuntime().set(suggestedRuntime);
+            explainJavaVersions.getReasoning().set(project.provider(() -> isLibrary(project, projectVersions)
+                    .toString()));
+        });
     }
 
-    private static boolean isLibrary(Project project, BaselineJavaVersionExtension projectVersions) {
+    private static IsLibraryWithReason isLibrary(Project project, BaselineJavaVersionExtension projectVersions) {
         Property<Boolean> libraryOverride = projectVersions.overrideLibraryAutoDetection();
         if (libraryOverride.isPresent()) {
-            log.debug(
-                    "Project '{}' is considered a library because it has been overridden with library = true",
-                    project.getDisplayName());
-            return libraryOverride.get();
+            return new IsLibraryWithReason(
+                    libraryOverride.get(), "has been overridden with `library = " + libraryOverride.get() + "`");
         }
 
         for (String plugin : LIBRARY_PLUGINS) {
             if (project.getPluginManager().hasPlugin(plugin)) {
-                log.debug(
-                        "Project '{}' is considered a library because the '{}' plugin is applied",
-                        project.getDisplayName(),
-                        plugin);
-                return true;
+                return new IsLibraryWithReason(true, String.format("has the '%s' plugin applied", plugin));
             }
         }
 
         for (String plugin : DISTRIBUTION_PLUGINS) {
             if (project.getPluginManager().hasPlugin(plugin)) {
-                log.debug(
-                        "Project '{}' is considered a distribution because the '{}' plugin is applied",
-                        project.getDisplayName(),
-                        plugin);
-                return false;
+                return new IsLibraryWithReason(false, String.format("has the '%s' plugin applied", plugin));
             }
         }
 
         PublishingExtension publishing = project.getExtensions().findByType(PublishingExtension.class);
         if (publishing == null) {
-            log.debug(
-                    "Project '{}' is considered a distribution, not a library, because "
-                            + "it doesn't define any publishing extensions",
-                    project.getDisplayName());
-            return false;
+            return new IsLibraryWithReason(false, "doesn't have any publishing extensions defined");
         }
 
         // Better to be conservative with the java version rather than release something that is too high to be used.
-        log.debug("Project '{}' is considered a library as no other conditions matched", project.getDisplayName());
-        return true;
+        return new IsLibraryWithReason(
+                true,
+                String.join(
+                        "\n",
+                        "didn't match any other conditions that would indicate it was a distribution:",
+                        "  * It did not have a distribution plugin: " + DISTRIBUTION_PLUGINS,
+                        "  * It had a publishing extension, indicating *something* that isn't a known "
+                                + "distribution type is being published. The publications in this extensions are "
+                                + publishing.getPublications().getNames(),
+                        String.format(
+                                "Despite not having any library publish plugins (%s), this is conservatively "
+                                        + "regarded as a library for safety.",
+                                LIBRARY_PLUGINS)));
+    }
+
+    private record IsLibraryWithReason(boolean isLibrary, String reason) {
+        @Override
+        public String toString() {
+            return String.format("considered a %s because it %s", isLibrary ? "library" : "distribution", reason);
+        }
     }
 }

gradle-baseline-java/src/main/java/com/palantir/baseline/plugins/javaversions/ExplainJavaVersions.java

@@ -0,0 +1,63 @@
+/*
+ * (c) Copyright 2025 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.baseline.plugins.javaversions;
+
+import org.gradle.api.DefaultTask;
+import org.gradle.api.provider.Property;
+import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.TaskAction;
+
+public abstract class ExplainJavaVersions extends DefaultTask {
+    @Input
+    public abstract Property<ChosenJavaVersion> getTarget();
+
+    @Input
+    public abstract Property<ChosenJavaVersion> getDefaultTarget();
+
+    @Input
+    public abstract Property<ChosenJavaVersion> getRuntime();
+
+    @Input
+    public abstract Property<ChosenJavaVersion> getDefaultRuntime();
+
+    @Input
+    public abstract Property<String> getReasoning();
+
+    @TaskAction
+    public final void action() {
+        getLogger()
+                .lifecycle(
+                        "target  = {} {}",
+                        getTarget().get().toString(),
+                        defaultValueChanged(getTarget(), getDefaultTarget()));
+
+        getLogger()
+                .lifecycle(
+                        "runtime = {} {}",
+                        getRuntime().get().toString(),
+                        defaultValueChanged(getRuntime(), getDefaultRuntime()));
+
+        getLogger().lifecycle("Reason: {}", getReasoning().get());
+    }
+
+    private static String defaultValueChanged(
+            Property<ChosenJavaVersion> actualValue, Property<ChosenJavaVersion> defaultValue) {
+        return actualValue.get().equals(defaultValue.get())
+                ? "(default value)"
+                : String.format("(default value was %s - changed by a Gradle script or plugin)", defaultValue.get());
+    }
+}

gradle-baseline-java/src/test/groovy/com/palantir/baseline/BaselineJavaVersionIntegrationTest.groovy

@@ -690,6 +690,28 @@ class BaselineJavaVersionIntegrationTest extends IntegrationSpec {
         gradleVersionNumber << GRADLE_TEST_VERSIONS
     }
 
+
+    def '#gradleVersionNumber: explainJavaVersions prints the java version used'() {
+        fork = false
+        buildFile << '''
+            javaVersions {
+                libraryTarget = 11
+                runtime = 17
+            }
+        '''.stripIndent(true)
+
+        when:
+        def stdout = runTasksSuccessfully('explainJavaVersions').standardOutput
+
+        then:
+        stdout.contains('target  = 11')
+        stdout.contains('runtime = 17')
+        stdout.contains('Reason:')
+
+        where:
+        gradleVersionNumber << GRADLE_TEST_VERSIONS
+    }
+
     private static final int BYTECODE_IDENTIFIER = (int) 0xCAFEBABE
 
     // See http://illegalargumentexception.blogspot.com/2009/07/java-finding-class-versions.html

versions.lock

@@ -81,13 +81,13 @@ org.slf4j:slf4j-api:1.7.36 (9 constraints: ac87f044)
 
 [Test dependencies]
 cglib:cglib-nodep:3.2.2 (1 constraints: 490ded24)
-com.fasterxml.jackson.core:jackson-annotations:2.18.2 (7 constraints: cf6bd751)
-com.fasterxml.jackson.core:jackson-core:2.18.2 (6 constraints: af7eecb6)
-com.fasterxml.jackson.core:jackson-databind:2.18.2 (13 constraints: a9fa5bda)
-com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.2 (1 constraints: e9130670)
-com.fasterxml.jackson.datatype:jackson-datatype-guava:2.18.2 (1 constraints: e9130670)
-com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.2 (1 constraints: e9130670)
-com.fasterxml.jackson.module:jackson-module-afterburner:2.18.2 (1 constraints: 3f05493b)
+com.fasterxml.jackson.core:jackson-annotations:2.18.3 (7 constraints: d16bf053)
+com.fasterxml.jackson.core:jackson-core:2.18.3 (6 constraints: b47e5aba)
+com.fasterxml.jackson.core:jackson-databind:2.18.3 (13 constraints: aefa76e5)
+com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.3 (1 constraints: e9130670)
+com.fasterxml.jackson.datatype:jackson-datatype-guava:2.18.3 (1 constraints: e9130670)
+com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.3 (1 constraints: e9130670)
+com.fasterxml.jackson.module:jackson-module-afterburner:2.18.3 (1 constraints: 40054a3b)
 com.github.stefanbirkner:system-rules:1.19.0 (1 constraints: 3d05443b)
 com.google.auto.value:auto-value:1.10 (1 constraints: e711f8e8)
 com.google.errorprone:error_prone_test_helpers:2.36.0 (1 constraints: 38053a3b)

versions.props

@@ -1,4 +1,4 @@
-com.fasterxml.jackson.core:jackson-databind = 2.18.2
+com.fasterxml.jackson.core:jackson-databind = 2.18.3
 com.github.ben-manes.caffeine:caffeine = 3.2.0
 com.google.auto.service:auto-service = 1.1.1
 com.google.guava:guava = 33.4.0-jre
@@ -22,7 +22,7 @@ com.palantir.gradle.failure-reports:* = 1.2.0
 
 
 # test deps
-com.fasterxml.jackson.*:* = 2.18.2
+com.fasterxml.jackson.*:* = 2.18.3
 com.github.stefanbirkner:system-rules = 1.19.0
 com.netflix.nebula:nebula-test = 10.6.2
 com.palantir.conjure.java:* = 8.45.0