Introduce appendix section with version properties

With the introduction of Gradle we lost the list of version properties
that were previously in the spring-boot-dependencies POM and were also
linked inside the documentation. This commit introduces an appendix
section in the docs and links the appropriate places to the new section
to restore discoverability.

See gh-19898

Author: dreis2211

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[]
+
+[[version-properties]]
+== Version Properties
+
+The following table provides all version 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#version-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}/#version-properties
 :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}[`Version Properties Appendix`] in the Spring Boot reference for a complete list of version 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: