Skip to content

Commit 3328a30

Browse files
committed
Include details of dependency versions in the docs
Closes spring-projects#637
1 parent 307fbba commit 3328a30

File tree

7 files changed

+125
-40
lines changed

7 files changed

+125
-40
lines changed

spring-boot-docs/pom.xml

Lines changed: 73 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,79 @@
7070
</execution>
7171
</executions>
7272
</plugin>
73+
<plugin>
74+
<groupId>org.apache.maven.plugins</groupId>
75+
<artifactId>maven-dependency-plugin</artifactId>
76+
<executions>
77+
<execution>
78+
<id>unpack-maven-plugin</id>
79+
<phase>generate-resources</phase>
80+
<goals>
81+
<goal>unpack</goal>
82+
</goals>
83+
<configuration>
84+
<artifactItems>
85+
<artifactItem>
86+
<groupId>org.springframework.boot</groupId>
87+
<artifactId>spring-boot-maven-plugin</artifactId>
88+
<version>${project.version}</version>
89+
<classifier>site</classifier>
90+
<type>jar</type>
91+
<outputDirectory>
92+
${project.build.directory}/contents/maven-plugin
93+
</outputDirectory>
94+
<excludes>META-INF/**</excludes>
95+
</artifactItem>
96+
</artifactItems>
97+
</configuration>
98+
</execution>
99+
<execution>
100+
<id>unpack-dependency-tools-effective-pom</id>
101+
<phase>generate-resources</phase>
102+
<goals>
103+
<goal>unpack</goal>
104+
</goals>
105+
<configuration>
106+
<artifactItems>
107+
<artifactItem>
108+
<groupId>org.springframework.boot</groupId>
109+
<artifactId>spring-boot-dependency-tools</artifactId>
110+
<version>${project.version}</version>
111+
<type>jar</type>
112+
</artifactItem>
113+
</artifactItems>
114+
<includes>**/effective-pom.xml</includes>
115+
<outputDirectory>${project.build.directory}/external-resources</outputDirectory>
116+
</configuration>
117+
</execution>
118+
</executions>
119+
</plugin>
120+
<plugin>
121+
<groupId>org.codehaus.mojo</groupId>
122+
<artifactId>xml-maven-plugin</artifactId>
123+
<version>1.0</version>
124+
<executions>
125+
<execution>
126+
<goals>
127+
<goal>transform</goal>
128+
</goals>
129+
</execution>
130+
</executions>
131+
<configuration>
132+
<transformationSets>
133+
<transformationSet>
134+
<dir>${project.build.directory}/external-resources</dir>
135+
<stylesheet>src/main/xslt/dependencyVersions.xsl</stylesheet>
136+
<fileMappers>
137+
<fileMapper implementation="org.codehaus.plexus.components.io.filemappers.FileExtensionMapper">
138+
<targetExtension>.adoc</targetExtension>
139+
</fileMapper>
140+
</fileMappers>
141+
<outputDir>${project.build.directory}/generated-resources</outputDir>
142+
</transformationSet>
143+
</transformationSets>
144+
</configuration>
145+
</plugin>
73146
<plugin>
74147
<groupId>org.asciidoctor</groupId>
75148
<artifactId>asciidoctor-maven-plugin</artifactId>
@@ -219,34 +292,6 @@
219292
</execution>
220293
</executions>
221294
</plugin>
222-
<plugin>
223-
<groupId>org.apache.maven.plugins</groupId>
224-
<artifactId>maven-dependency-plugin</artifactId>
225-
<executions>
226-
<execution>
227-
<id>unpack-maven-plugin</id>
228-
<phase>generate-resources</phase>
229-
<goals>
230-
<goal>unpack</goal>
231-
</goals>
232-
<configuration>
233-
<artifactItems>
234-
<artifactItem>
235-
<groupId>org.springframework.boot</groupId>
236-
<artifactId>spring-boot-maven-plugin</artifactId>
237-
<version>${project.version}</version>
238-
<classifier>site</classifier>
239-
<type>jar</type>
240-
<outputDirectory>
241-
${project.build.directory}/contents/maven-plugin
242-
</outputDirectory>
243-
<excludes>META-INF/**</excludes>
244-
</artifactItem>
245-
</artifactItems>
246-
</configuration>
247-
</execution>
248-
</executions>
249-
</plugin>
250295
<plugin>
251296
<groupId>org.apache.maven.plugins</groupId>
252297
<artifactId>maven-antrun-plugin</artifactId>
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[appendix]
2+
[[appendix-dependency-versions]]
3+
== Dependency versions
4+
The table below provides details of all of the dependency versions that are provided by Spring Boot
5+
in its CLI, Maven dependency management and Gradle plugin. When you declare a dependency on one of
6+
these artifacts without declaring a version the version that is listed in the table will be used.
7+
8+
include::../../../target/generated-resources/org/springframework/boot/dependency/tools/effective-pom.adoc[]

spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -275,3 +275,5 @@ alternatives could be considered:
275275
* http://maven.apache.org/plugins/maven-shade-plugin/[Maven Shade Plugin]
276276
* http://www.jdotsoft.com/JarClassLoader.php[JarClassLoader]
277277
* http://one-jar.sourceforge.net[OneJar]
278+
279+

spring-boot-docs/src/main/asciidoc/appendix.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@
44
include::appendix-application-properties.adoc[]
55
include::appendix-auto-configuration-classes.adoc[]
66
include::appendix-executable-jar-format.adoc[]
7+
include::appendix-dependency-versions.adoc[]
78

spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -202,12 +202,8 @@ If you are using a milestone or snapshot release you will also need to add appro
202202
=== Declaring dependencies without versions
203203
The `spring-boot` plugin will register a custom Gradle `ResolutionStrategy` with your
204204
build that allows you to omit version numbers when declaring dependencies to ``blessed''
205-
artifacts. All artifacts with a `org.springframework.boot` group ID, and any of the
206-
artifacts declared in the `managementDependencies` section of the
207-
{github-code}/spring-boot-dependencies/pom.xml[`spring-dependencies`]
208-
POM can have their version number resolved automatically.
209-
210-
Simply declare dependencies in the usual way, but leave the version number empty:
205+
artifacts. To make use of this functionality, simply declare dependencies in the usual way,
206+
but leave the version number empty:
211207

212208
[source,groovy,indent=0,subs="verbatim,attributes"]
213209
----
@@ -221,9 +217,20 @@ Simply declare dependencies in the usual way, but leave the version number empty
221217
NOTE: The version of the `spring-boot` gradle plugin that you declare determines the
222218
actual versions of the ``blessed'' dependencies (this ensures that builds are always
223219
repeatable). You should always set the version of the `spring-boot` gradle plugin to the
224-
actual Spring Boot version that you wish to use.
220+
actual Spring Boot version that you wish to use. Details of the versions that are
221+
provided can be found in the <<appendix-dependency-versions, appendix>>.
225222

223+
The `spring-boot` plugin will only supply a version where one is not specified. To
224+
use a version of an artifact that differs from the one that the plugin would provide,
225+
simply specify the version when you declare the dependency as you usually would. For
226+
example:
226227

228+
[source,groovy,indent=0,subs="verbatim,attributes"]
229+
----
230+
dependencies {
231+
compile("org.thymeleaf:thymeleaf-spring4:2.1.1.RELEASE")
232+
}
233+
----
227234

228235
[[build-tool-plugins-gradle-custom-version-management]]
229236
==== Custom version management
@@ -250,8 +257,6 @@ the above example `mycorp-versions.properties` file might contain the following:
250257
The properties file takes precedence over Spring Boot's defaults, and can be used
251258
to override version numbers if necessary.
252259

253-
254-
255260
[[build-tool-plugins-gradle-packaging]]
256261
=== Packaging executable jar and war files
257262
Once the `spring-boot` plugin has been applied to your project it will automatically
@@ -520,8 +525,6 @@ Here is a typical example repackage:
520525
});
521526
----
522527

523-
524-
525528
[[build-tool-plugins-whats-next]]
526529
== What to read next
527530
If you're interested in how the build tool plugins work you can

spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,8 @@ without a group or version, for example `@Grab('freemarker')`. This will consult
160160
default dependency metadata to deduce the artifact's group and version. Note that the default
161161
metadata is tied to the version of the CLI that you're using – it will only change when you move
162162
to a new version of the CLI, putting you in control of when the versions of your dependencies
163-
may change.
163+
may change. A table showing the dependencies and their versions that are included in the default
164+
metadata can be found in the <<appendix-dependency-versions, appendix>>.
164165

165166

166167

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<?xml version="1.0"?>
2+
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
3+
xmlns:mvn="http://maven.apache.org/POM/4.0.0"
4+
version="1.0">
5+
6+
<xsl:output method="text" encoding="UTF-8" indent="no"/>
7+
8+
<xsl:template match="/">
9+
<xsl:text>|==================================&#xa;</xsl:text>
10+
<xsl:text>| Group ID | Artifact ID | Version&#xa;</xsl:text>
11+
<xsl:for-each select="//mvn:dependency">
12+
<xsl:sort select="mvn:groupId"/>
13+
<xsl:sort select="mvn:artifactId"/>
14+
<xsl:text>| </xsl:text>
15+
<xsl:copy-of select="mvn:groupId"/>
16+
<xsl:text> | </xsl:text>
17+
<xsl:copy-of select="mvn:artifactId"/>
18+
<xsl:text> | </xsl:text>
19+
<xsl:copy-of select="mvn:version"/>
20+
<xsl:text>&#xa;</xsl:text>
21+
</xsl:for-each>
22+
<xsl:text>|==================================</xsl:text>
23+
</xsl:template>
24+
25+
</xsl:stylesheet>

0 commit comments

Comments
 (0)