A side effect of 71995a9087 caused the
dynamic table of contents in the left-hand side navigation to no longer
be displayed, likely due to the missing "details" DIV.
This commit addresses this issue by applying the custom header only to
index.adoc.
Consequently, the TOC is now displayed again on all pages except the
index page, but the customized header is no longer applied to those
pages.
We may revisit this issue if we decide that we want the custom header
on all pages (and not just the index page).
Closes gh-27177
This commit defines the doc-root and api-spring-framework attributes
once in docs.gradle instead of duplicating them in each *.adoc file.
This commit also introduces a new docs-spring-framework global
attribute.
This commit disables the automatic header generation from Asciidoc's
default template and replaces it with a custom header that omits the
"Version" label before the revision number. The revision number is also
displayed in a simple span tag in order to reduce the amount of
vertical space taken by the header.
Prior to this commit, we registered custom values in the build scan for
the main and test toolchains based on input values provided via the
mainToolchain and testToolchain project properties.
Beginning with this commit, the custom values we register are based on
the available metadata for the resolved JDK/JVM for each toolchain.
For example, instead of registering the following custom value...
Test toolchain : JDK11
... we now register the following which includes the vendor, version,
and installation path of the JDK/JVM.
Test toolchain : AdoptOpenJDK 11 (/Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home)
Once Gradle's JavaInstallationMetadata includes the exact version, we
will likely use that instead of the installation path.
See gh-25787
Commit 3eec27a723 introduced a custom resource filter for projects
imported into Eclipse IDE. However, commit 85eb589c2e introduced
generated source files within the Gradle 'build' folder, and the filter
prevents Eclipse from seeing the generated sources, resulting in build
errors within the spring-oxm project in Eclipse.
This commit therefore effectively reverts 3eec27a723 by removing the
resource filter.
See gh-25787
This commit fixes various issues with the configuration of the Gradle
Java toolchain in the build.
First, the configuration of build properties is fixed in the CI pipeline
because it wasn't properly checked.
The JMH plugin is also upgraded and we now configure its toolchain
support.
This commit also rewrites the XJC tasks in the spring-oxm module,
leveraging a Gradle plugin that creates actual compile tasks we can
configure.
See gh-25787
Prior to this commit, the Spring Framework build would rely on
setting a custom Java HOME for building all sources and tests
with that JDK.
This approach is not flexible enough, since we would be testing
the source compatibility against a recent JDK, but not a common
case experienced by the community: compiling and running
application code with a recent JDK and the official, JDK8-based
Framework artifacts.
This method is also limiting our choice of JDKs to the ones
currently supported by Gradle itself.
This commit introduces the support of Gradle JVM Toolchains in
the Spring Framework build.
We can now select a specific JDK for compiling the main
SourceSets (Java, Groovy and Kotlin) and another one for
compiling and running the test SourceSets:
`./gradlew check -PmainToolChain=8 -PtestToolchain=15`
Gradle will automatically find the JDKs present on the host or
download one automcatically. You can find out about the ones
installed on your host using:
`./gradlew -q javaToolchains`
Finally, this commit also refactors the CI infrastructure to:
* only have a single CI image (with all the supported JDKs)
* use this new feature to compile with JDK8 but test it
against JDK11 and JDK15.
Closes gh-25787
Recently the Spring Framework projects could no longer be imported into
Eclipse IDE without compilation errors in JMH sources.
This commit addresses this issue by applying workarounds for bugs in
Gradle and the JMH plugin for Gradle.
Gradle bug: https://github.com/gradle/gradle/issues/14932
JMH plugin bug: https://github.com/melix/jmh-gradle-plugin/issues/157
The Gradle bug has already been fixed in Gradle 6.8 RC1; however, the
issue for the JMH plugin bug seems not to have been triaged yet.
Closes gh-26140
Prior to this commit, the `docsZip` task would not reference the new
output locations for the `asciidoctor` and `asciidoctorPdf` tasks.
This results with missing reference docs in the docs zip.
This commit updates the input locations of the Zip task to include the
produced reference docs.
Fixes gh-25783
Prior to this commit, the asciidoctor Gradle task was configured to
generate both the HTML5 and PDF backends. Unfortunately, this resulted
in resources such as HTML, JavaScript, CSS, and images being published
alongside the generated PDF documents.
This commit addresses this issue by introducing the use of a dedicated
asciidoctorPdf Gradle task. The existing asciidoctor Gradle task has
been modified to only generate HTML5 output. Both of these tasks now
share common configuration supplied by the updated asciidoctorj Gradle
task.
In addition, the asciidoctor task now depends on the asciidoctorPdf
task. Thus, invoking `./gradlew asciidoctor` will still generate both
the HTML5 and PDF outputs; whereas, `./gradlew asciidoctorPdf` will
generate only the PDF outputs. We may later decide to rework the tasks
to introduce a dedicated asciidoctorHtml task so that we can generate
the HTML outputs without having to generate the PDF outputs (which are
more time consuming).
See gh-25783
Prior to this commit, the asciidoctor Gradle task was configured to
generate both the HTML5 and PDF backends. Unfortunately, this resulted
in resources such as HTML, JavaScript, CSS, and images being published
alongside the generated PDF documents.
This commit addresses this issue by introducing the use of a dedicated
asciidoctorPdf Gradle task. The existing asciidoctor Gradle task has
been modified to only generate HTML5 output. Both of these tasks now
share common configuration supplied by the updated asciidoctorj Gradle
task.
In addition, the asciidoctor task now depends on the asciidoctorPdf
task. Thus, invoking `./gradlew asciidoctor` will still generate both
the HTML5 and PDF outputs; whereas, `./gradlew asciidoctorPdf` will
generate only the PDF outputs. We may later decide to rework the tasks
to introduce a dedicated asciidoctorHtml task so that we can generate
the HTML outputs without having to generate the PDF outputs (which are
more time consuming).
See gh-25783
This is done:
- For consistency with other Spring projects
- Because it is probably a better option to use reference instead of
spring-framework-reference (spring-framework is already present in
the URL)
- To improve PDF documentation discoverability
As a consequence:
- spring-framework-reference HTML documentation is now published
under reference/html
- spring-framework-reference/pdf PDF documentation is now published
under reference/pdf
The following permanent redirect should be created before Spring
Framework 5.3.0 release:
- current/spring-framework-reference/pdf/* to current/reference/pdf/*
- current/spring-framework-reference/* to current/reference/html/*
Closes gh-25071
Prior to this commit, the Spring Framework test suite would rely only on
"Performance" tests associated with a specific CI build. As outlined in
gh-24830, the way they're built and executed is not working well
anymore.
This commit introduces a new JMH benchmark infrastructure in the build.
The goal here is not to run those benchmarks as part of a CI build, but
rather provide a proper infrastructure for writing and locally running
micro-benchmarks when working on specific optimizations.
This commit adds and configures a Gradle JMH plugin to allow for JMH
benchmark classes in Spring Framework modules (in `src/jmh/java` of each
`spring-*` module). It's also relaxing the checkstyle rules for JMH
classes, especially around Javadoc rules: this code is not meant to
have Javadocs.
Finally, this commit links to a new Wiki page on the project GitHub
repository documenting the infrastructure and helping contributors to
run and design benchmarks.
See gh-24830
The `images` folder contains some files used to create the images, such
as OmniGraffle and SVG.
This commit modifies the `include` pattern to ensure that only `*.png`
files are copied from the source folder to the published reference
manual.
- Build Scan plugin is now Gradle Enterprise plugin applied in settings
- Compile task dependencies are now defined through classpath
- Test fixture publication can be disabled through public API
Closes gh-24384
As we're moving the build to Concourse CI, we don't need to use the
Artifactory plugin anymore. Our build will publish the artifacts to a
repository on the local filesystem and will push its content to
Artifactory with the spring-io/artifactory-resource.
This commit also adds the conditional configuration for publishing to a
local repository.
See gh-22490
This commit updates the spring-doc-resources version to 0.2.0 to get the
latest look and feel in the HTML version of the reference manual.
Closes gh-24831
A change in `docs.gradle` in 5.2.4 resulted in distribution zip files
no longer being published to
https://repo.spring.io/release/org/springframework/spring/.
This commit fixes this by updating the `mavenContent` configuration as
suggested by @wilkinsona.
Closes gh-24605
Setting `options.fork = true` causes the classpath in the forked
compiler process to include Class-Path entries from MANIFEST.MF files
in JARs in the classpath, which results in warnings about missing
classpath entries.
This commit removes the `options.fork = true` declaration and further
simplifies the script.
See gh-24474
0.4.0 provides built-in support for remembering a user's selections
using local storage. This replaces the custom switch language
JavaScript.
The selection is stored using a key derived from the
options that were available. Concretely, when the options are Java or
Kotlin, the local storage key is java-kotlin. Similarly, if the
choices were Java, Kotlin, and XML, the key would be java-kotlin-xml.
Given local storage's domain and protocol scoping, the nature of the
key that's used for storage will allow a user's selections to be
applied across all documentation hosted on https://docs.spring.io that
offer the same options.
Closes gh-24481
Prior to this commit, the "-Werror" was removed as a command-line
argument in order not to fail the build for missing classpath elements.
This commit reinstates "-Werror" and removes "-Xlink:path" in order to
explicitly ignore warnings for missing classpath elements when executing
the build with a custom JAVA_HOME.
See gh-24474
This commit adds support for the following two JVM system properties
that control the Gradle build for alternative JDKs (i.e., a JDK other
than the one used to launch the Gradle process).
- customJavaHome: absolute path to the alternate JDK installation to
use to compile Java code and execute tests. Setting this system
property causes Groovy 3.0 RC3 to be used instead of 2.5.x. This
system property is also used in spring-oxm.gradle to determine
whether JiBX is supported.
- customJavaSourceVersion: Java version supplied to the `--release`
command line flag to control the Java source and target compatibility
version. Supported versions include 9 or higher. Do not set this
system property if Java 8 should be used.
Examples:
./gradlew -DcustomJavaHome=/opt/java/jdk-14 test
./gradlew --no-build-cache -DcustomJavaHome=/opt/java/jdk-14 test
./gradlew -DcustomJavaHome=/opt/java/jdk-14 -DcustomJavaSourceVersion=14 test
See gh-24474
Previously, the Asciidoctor task was not cacheable and generating the
PDF documentation was very slow. To improve build times, the PDF
documentation was not generated for snapshot builds.
The upgrade to 2.4.0 of the Asciidoctor Gradle pluging means that the
Asciidoctor task is now cacheable. As such, its tasks will only run
when the documentation has changed. This should allow PDF
documentation to be published for every build without slowing things
down too much and the cost of generating the documentation will only
be incurred when there is a change to the documentation.
See gh-24216
This commit updates the build to use the latest version of the
Asciidoctor Gradle Plugin. One significant new feature is that the
plugin's tasks are now cacheable.
Closes gh-24216
Previously, the remote build cache was only enabled if the
GRADLE_ENTERPRISE_URL environment variable was configured. This meant
that contributors would not benefit from the build time improvements
of the caching without some additional setup.
This commit updates the buildCache configuration so that reading from
the remote build cache at https://ge.spring.io is enabled for all.
Pushing to the cache continues to be disabled unless the required
credentials are provided. Build scan configuration has also been
updated in line with this change. While the server URL is now
hardcoded, publishing is still opt-in via an environment variable.
The exact mechanism by which someone can opt in will change in the
future once some server-side changes have been made. At this point,
only a change to publishAlwaysIf should be necessary.
Closes gh-24105
Prior to this commit, the schemaZip Gradle task failed to find Spring
schema files on MS Windows due to path separators hard coded to forward
slashes that are not compatible with the Windows operating system.
Consequently, a full build failed on Windows since the distZip task was
not able to locate the zipped schema archive that the schemaZip task
failed to create.
This commit fixes this by updating the schemaZip task to search for
schema files using backslashes as well as forward slashes.
Closes gh-23933
This commit provides opt-in enablement of Gradle's remote build
cache. When the GRADLE_ENTERPRISE_URL environment variable is set, its
build cache node will be used as a source of cached output. If both
GRADLE_ENTERPRISE_CACHE_USERNAME and GRADLE_ENTERPRISE_CACHE_PASSWORD
are also set, task output produced by the build will be pushed to the
build cache node for use by subsequent builds.
Closes gh-23883
Previously, when a project's jar was an input into a test task, a
cache hit required the current build to be using the same JDK as the
one that created the cache entry. This was due to the Created-By
entry in the jar's manifest which will vary if JDKs with different
values for the java.version and java.specification.vendor version are
used.
This commit configures normalization of the runtime classpath to ignore
META-INF/MANIFEST.MF, thereby allowing a cache hit when the tests were
previously run on a different JDK than the one being used now. Typically
this is a different update release being used on a CI agent and a
developer's machine. This change will therefore improve the likelihood
of a cache hit once remote caching has been enabled.
Closes gh-23872
The parallel forks configuration of Test tasks can have a big impact
on their execution time. This commit updates the build can
configuration to capture each Test task's maxParallelForks
configuration as custom values in the build scan. This will make this
data available when comparing scans which will be useful as we
experiment with different parallel fork settings to reduce the
build's overall execution time.
Closes gh-23691
When exposed as an environment variable Bamboo's bamboo.resultsUrl
is mapped to bamboo_resultsUrl. This commit updates the build scan
user data script to look for the latter rather than the former.
Closes gh-23597
When exposed as an environment variable Bamboo's bamboo.resultsUrl
is mapped to bamboo_resultsUrl. This commit updates the build scan
user data script to look for the latter rather than the former.
When exposed as an environment variable Bamboo's bamboo.resultsUrl
is mapped to bamboo_resultsUrl. This commit updates the build scan
user data script to look for the latter rather than the former.
This commit adds opt-in build scan integration with Gradle Enterprise.
When the GRADLE_ENTERPRISE_URL environment variable is set on a
developer's machine or on CI, a build scan will be automatically
uploaded to Gradle Enterprise at the end of the build.
This initial integration will establish a baseline for Spring
Framework builds. Once that baseline has been established we can use
the build scans to identify ways in which the build can be optimized
and updated to make use of Gradle's build caching which should reduce
build times, significantly so for changes that only affect tasks near
the leaf nodes of the task graph.
This commit ensures that Gradle publications are using resolved
dependency versions for Maven publications (i.e. POMs). This is useful
since we're using the Spring dependency management plugin and we can't
rely on declared dependency versions only.
See gh-23282
Instead of relying on the CI server to apply and configure this plugin,
this commit does it directly in the Spring Framework build.
This allows us to take full control over which projects are published
and how.
See gh-23282
This commit switches to the default publication name considered by the
artifactory plugin when it comes to publishing artifacts to the
artifactory repository.
See gh-23282
Prior to this commit, the build would use a custom task to create a BOM
and manually include/exclude/customize dependencies. It would also use
the "maven" plugin to customize the POM before publication.
This commit now uses a Gradle Java Platform for publishing the Spring
Framework BOM. We're also now using the "maven-publish" plugin to
prepare and customize publications.
This commit also tells the artifactory plugin (which is currently
applied only on the CI) not to publish internal modules.
See gh-23282
This commit configures the Gradle Download plugin that's used a build
step when generating the reference documentation. Here we're making sure
that the task is caching and reusing the resource if it's been
downloaded already.
See gh-23282
Prior to this commit, the reference documentation build with asciidoctor
would get the common "spring-docs-resources" as a dependency and then
use it when generating the docs.
As seen in #23124, this can cause problems since we'd like to
consistently resolve our dependencies. In this case, the
"spring-doc-resources" archive is not published on maven central since
it's not officially supported by the Spring team as an open source
project.
This commit updates the reference documentation build to get this
archive as a simple download task and avoid resolving it as a
dependency.
See gh-23282
Brian Clozel
Sam Brannen
Arjen Poutsma
Stephane Nicoll
Sébastien Deleuze
Brian Clozel
Sam Brannen
Jendrik Johannes
Sam Brannen
Jay Bryant
Sébastien Deleuze
Andy Wilkinson
Rob Winch
YuDongYing
Johnny Lim
Stephane Nicoll