From 65394582f609f06bbaa34827aa81bd7e9cf50b01 Mon Sep 17 00:00:00 2001 From: dreis2211 Date: Fri, 24 Jan 2020 09:22:03 +0100 Subject: [PATCH] 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 --- .../DocumentVersionProperties.java | 80 +++++++++++++++++++ .../ExtractVersionConstraints.java | 49 ++++++++++++ .../spring-boot-docs/build.gradle | 9 +++ .../appendix-dependency-versions.adoc | 8 ++ .../src/docs/asciidoc/howto.adoc | 2 +- .../src/docs/asciidoc/using-spring-boot.adoc | 2 +- .../src/docs/asciidoc/index.adoc | 1 + .../docs/asciidoc/managing-dependencies.adoc | 2 +- 8 files changed, 150 insertions(+), 3 deletions(-) create mode 100644 buildSrc/src/main/java/org/springframework/boot/build/constraints/DocumentVersionProperties.java diff --git a/buildSrc/src/main/java/org/springframework/boot/build/constraints/DocumentVersionProperties.java b/buildSrc/src/main/java/org/springframework/boot/build/constraints/DocumentVersionProperties.java new file mode 100644 index 0000000000..b8b2435ab6 --- /dev/null +++ b/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 versionProperties; + + private File outputFile; + + @Inject + public DocumentVersionProperties(ObjectFactory objectFactory) { + this.versionProperties = objectFactory.setProperty(VersionProperty.class); + } + + @Input + public SetProperty 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("|==="); + } + } + +} diff --git a/buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java b/buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java index d32cecfc92..23f368b3da 100644 --- a/buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java +++ b/buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java @@ -36,6 +36,9 @@ import org.gradle.api.tasks.Internal; 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 constrainedVersions = new TreeSet<>(); + private final Set versionProperties = new TreeSet<>(); + private final List projectPaths = new ArrayList(); public ExtractVersionConstraints() { @@ -74,10 +79,16 @@ public class ExtractVersionConstraints extends AbstractTask { return this.constrainedVersions; } + @Internal + public Set 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 @@ public class ExtractVersionConstraints extends AbstractTask { } } + 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 class ExtractVersionConstraints extends AbstractTask { } + public static final class VersionProperty implements Comparable, 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); + } + + } + } diff --git a/spring-boot-project/spring-boot-docs/build.gradle b/spring-boot-project/spring-boot-docs/build.gradle index 2a8d934ee7..5d45f324fc 100644 --- a/spring-boot-project/spring-boot-docs/build.gradle +++ b/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" diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc index e5049c86dc..9a4a996722 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc +++ b/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[] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc index 7bacd31290..75bc7dbeb5 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc +++ b/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 `` 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 <> 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"] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc index 46acc66513..025c3e7d9e 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc +++ b/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 ---- -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 <> for more information. diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc index f479f070f8..11fb35a8fc 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc +++ b/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 diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc index 9dd99322e6..6369621eb8 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc +++ b/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: