Merge pull request #19898 from dreis2211

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

Closes gh-19898
pull/19948/head
Stephane Nicoll 5 years ago
commit c624708cb7

@ -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("|===");
}
}
}

@ -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<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 class ExtractVersionConstraints extends AbstractTask {
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 @@ 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<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);
}
}
}

@ -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"

@ -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[]

@ -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"]

@ -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.

@ -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

@ -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:

Loading…
Cancel
Save