Merge pull request #19898 from dreis2211

* pr/19898:
  Polish "Introduce appendix section with version properties"
  Introduce appendix section with version properties

Closes gh-19898

Author: snicoll

buildSrc/src/main/java/org/springframework/boot/build/constraints/DocumentVersionProperties.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2019-2020 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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 org.springframework.boot.build.constraints;
+
+import java.io.File;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.io.PrintWriter;
+
+import javax.inject.Inject;
+
+import org.gradle.api.DefaultTask;
+import org.gradle.api.model.ObjectFactory;
+import org.gradle.api.provider.SetProperty;
+import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.OutputFile;
+import org.gradle.api.tasks.TaskAction;
+
+import org.springframework.boot.build.constraints.ExtractVersionConstraints.VersionProperty;
+
+/**
+ * Task for documenting available version properties.
+ *
+ * @author Christoph Dreis
+ */
+public class DocumentVersionProperties extends DefaultTask {
+
+	private final SetProperty<VersionProperty> versionProperties;
+
+	private File outputFile;
+
+	@Inject
+	public DocumentVersionProperties(ObjectFactory objectFactory) {
+		this.versionProperties = objectFactory.setProperty(VersionProperty.class);
+	}
+
+	@Input
+	public SetProperty<VersionProperty> getVersionProperties() {
+		return this.versionProperties;
+	}
+
+	@OutputFile
+	public File getOutputFile() {
+		return this.outputFile;
+	}
+
+	public void setOutputFile(File outputFile) {
+		this.outputFile = outputFile;
+	}
+
+	@TaskAction
+	public void documentVersionProperties() throws IOException {
+		this.outputFile.getParentFile().mkdirs();
+		try (PrintWriter writer = new PrintWriter(new FileWriter(this.outputFile))) {
+			writer.println("|===");
+			writer.println("| Library | Version Property");
+			for (VersionProperty versionProperty : this.versionProperties.get()) {
+				writer.println();
+				writer.printf("| `%s`%n", versionProperty.getLibraryName());
+				writer.printf("| `%s`%n", versionProperty.getVersionProperty());
+			}
+			writer.println("|===");
+		}
+	}
+
+}

buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java

@@ -36,6 +36,9 @@
 import org.gradle.api.tasks.TaskAction;
 import org.gradle.platform.base.Platform;
 
+import org.springframework.boot.build.bom.BomExtension;
+import org.springframework.boot.build.bom.Library;
+
 /**
  * {@link Task} to extract constraints from a {@link Platform}. The platform's own
  * constraints and those in any boms upon which it depends are extracted.
@@ -50,6 +53,8 @@ public class ExtractVersionConstraints extends AbstractTask {
 
 	private final Set<ConstrainedVersion> constrainedVersions = new TreeSet<>();
 
+	private final Set<VersionProperty> versionProperties = new TreeSet<>();
+
 	private final List<String> projectPaths = new ArrayList<String>();
 
 	public ExtractVersionConstraints() {
@@ -74,10 +79,16 @@ public Set<ConstrainedVersion> getConstrainedVersions() {
 		return this.constrainedVersions;
 	}
 
+	@Internal
+	public Set<VersionProperty> getVersionProperties() {
+		return this.versionProperties;
+	}
+
 	@TaskAction
 	void extractVersionConstraints() {
 		this.configuration.resolve();
 		for (String projectPath : this.projectPaths) {
+			extractVersionProperties(projectPath);
 			for (DependencyConstraint constraint : getProject().project(projectPath).getConfigurations()
 					.getByName("apiElements").getAllDependencyConstraints()) {
 				this.versionConstraints.put(constraint.getGroup() + ":" + constraint.getName(),
@@ -88,6 +99,14 @@ void extractVersionConstraints() {
 		}
 	}
 
+	private void extractVersionProperties(String projectPath) {
+		Object bom = getProject().project(projectPath).getExtensions().getByName("bom");
+		BomExtension bomExtension = (BomExtension) bom;
+		for (Library lib : bomExtension.getLibraries()) {
+			this.versionProperties.add(new VersionProperty(lib.getName(), lib.getVersionProperty()));
+		}
+	}
+
 	private void processMetadataDetails(ComponentMetadataDetails details) {
 		details.allVariants((variantMetadata) -> variantMetadata.withDependencyConstraints((dependencyConstraints) -> {
 			for (DependencyConstraintMetadata constraint : dependencyConstraints) {
@@ -136,4 +155,34 @@ public int compareTo(ConstrainedVersion other) {
 
 	}
 
+	public static final class VersionProperty implements Comparable<VersionProperty>, Serializable {
+
+		private final String libraryName;
+
+		private final String versionProperty;
+
+		public VersionProperty(String libraryName, String versionProperty) {
+			this.libraryName = libraryName;
+			this.versionProperty = versionProperty;
+		}
+
+		public String getLibraryName() {
+			return this.libraryName;
+		}
+
+		public String getVersionProperty() {
+			return this.versionProperty;
+		}
+
+		@Override
+		public int compareTo(VersionProperty other) {
+			int groupComparison = this.libraryName.compareToIgnoreCase(other.libraryName);
+			if (groupComparison != 0) {
+				return groupComparison;
+			}
+			return this.versionProperty.compareTo(other.versionProperty);
+		}
+
+	}
+
 }

spring-boot-project/spring-boot-docs/build.gradle

@@ -98,6 +98,12 @@ task documentDependencyVersions(type: org.springframework.boot.build.constraints
 	outputFile = file("${buildDir}/docs/generated/dependency-versions.adoc")
 }
 
+task documentVersionProperties(type: org.springframework.boot.build.constraints.DocumentVersionProperties) {
+	dependsOn dependencyVersions
+	versionProperties.set(providers.provider { dependencyVersions.versionProperties})
+	outputFile = file("${buildDir}/docs/generated/version-properties.adoc")
+}
+
 task documentConfigurationProperties(type: org.springframework.boot.build.context.properties.DocumentConfigurationProperties) {
 	configurationPropertyMetadata = configurations.configurationProperties
 	outputDir = file("${buildDir}/docs/generated/config-docs/")
@@ -152,6 +158,7 @@ syncDocumentationSourceForAsciidoctor {
 	dependsOn documentStarters
 	dependsOn documentAutoConfigurationClasses
 	dependsOn documentDependencyVersions
+	dependsOn documentVersionProperties
 	dependsOn documentConfigurationProperties
 	from("${buildDir}/docs/generated") {
 		into "asciidoc"
@@ -169,6 +176,7 @@ syncDocumentationSourceForAsciidoctorMultipage {
 	dependsOn documentStarters
 	dependsOn documentAutoConfigurationClasses
 	dependsOn documentDependencyVersions
+	dependsOn documentVersionProperties
 	dependsOn documentConfigurationProperties
 	from("${buildDir}/docs/generated") {
 		into "asciidoc"
@@ -186,6 +194,7 @@ syncDocumentationSourceForAsciidoctorPdf {
 	dependsOn documentStarters
 	dependsOn documentAutoConfigurationClasses
 	dependsOn documentDependencyVersions
+	dependsOn documentVersionProperties
 	dependsOn documentConfigurationProperties
 	from("${buildDir}/docs/generated") {
 		into "asciidoc"

spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc

@@ -12,3 +12,11 @@ The following table provides details of all of the dependency versions that are
 When you declare a dependency on one of these artifacts without declaring a version, the version listed in the table is used.
 
 include::dependency-versions.adoc[]
+
+[[dependency-versions-properties]]
+== Version Properties
+
+The following table provides all properties that can be used to override the versions managed by Spring Boot.
+Browse the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/build.gradle[`spring-boot-dependencies` build.gradle] for a complete list of dependencies.
+
+include::version-properties.adoc[]

spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc

@@ -2421,7 +2421,7 @@ Using this format lets the time be parsed into a `Date` and its format, when ser
 [[howto-customize-dependency-versions]]
 === Customize Dependency Versions
 If you use a Maven build that inherits directly or indirectly from `spring-boot-dependencies` (for instance, `spring-boot-starter-parent`) but you want to override a specific third-party dependency, you can add appropriate `<properties>` elements.
-Browse the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/pom.xml[`spring-boot-dependencies`] POM for a complete list of properties.
+Browse the <<appendix-dependency-versions.adoc#dependency-versions-properties, `Version properties`>> for a complete list of version properties.
 For example, to pick a different `slf4j` version, you would add the following property:
 
 [source,xml,indent=0,subs="verbatim,quotes,attributes"]

spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc

@@ -81,7 +81,7 @@ For instance, to upgrade to another Spring Data release train, you would add the
 	</properties>
 ----
 
-TIP: Check the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/pom.xml[`spring-boot-dependencies` pom] for a list of supported properties.
+TIP: Check out the <<howto.adoc#howto-customize-dependency-versions, Customize Dependency Versions "`How-to`">> for more information.
 
 
 

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc

@@ -25,6 +25,7 @@ Andy Wilkinson
 :spring-boot-docs: https://docs.spring.io/spring-boot/docs/{gradle-project-version}
 :api-documentation: {spring-boot-docs}/gradle-plugin/api
 :spring-boot-reference: {spring-boot-docs}/reference/htmlsingle
+:version-properties-appendix: {spring-boot-reference}/#dependency-versions-coordinates
 :build-info-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/buildinfo/BuildInfo.html
 :boot-build-image-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootBuildImage.html
 :boot-jar-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootJar.html

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc

@@ -23,7 +23,7 @@ include::../gradle/managing-dependencies/dependencies.gradle.kts[tags=dependenci
 === Customizing managed versions
 
 The `spring-boot-dependencies` bom that is automatically imported when the dependency management plugin is applied uses properties to control the versions of the dependencies that it manages.
-Please refer to the {github-code}/spring-boot-project/spring-boot-dependencies/pom.xml[bom] for a complete list of these properties.
+Browse the {version-properties-appendix}[`Dependency versions Appendix`] in the Spring Boot reference for a complete list of these properties.
 
 To customize a managed version you set its corresponding property.
 For example, to customize the version of SLF4J which is controlled by the `slf4j.version` property: