// Copyright 2019 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
//
//      http://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.

[[upgrading_version_6]]
= Upgrading your build from Gradle 6.x to 7.0

This chapter provides the information you need to migrate your Gradle 6.x builds to Gradle 7.0.
For migrating from Gradle 5.x or earlier, complete the <<upgrading_version_5.adoc#upgrading_version_5, older migration guide>> first.

We recommend the following steps for all users:

. Try running `gradle help --scan` and view the https://gradle.com/enterprise/releases/2018.4/#identify-usages-of-deprecated-gradle-functionality[deprecations view] of the generated build scan.
+
image::deprecations.png[Deprecations View of a Gradle Build Scan]
+
This is so that you can see any deprecation warnings that apply to your build.
+
Alternatively, you can run `gradle help --warning-mode=all` to see the deprecations in the console, though it may not report as much detailed information.
. Update your plugins.
+
Some plugins will break with this new version of Gradle, for example because they use internal APIs that have been removed or changed.
The previous step will help you identify potential problems by issuing deprecation warnings when a plugin does try to use a deprecated part of the API.
+
. Run `gradle wrapper --gradle-version 7.0` to update the project to 7.0.
. Try to run the project and debug any errors using the <<troubleshooting.adoc#troubleshooting, Troubleshooting Guide>>.

[[changes_7.0]]
== Upgrading from 6.9 and earlier

=== Changes in the IDE integration

==== Changes in the IDEA model

The `getGeneratedSourceDirectories()` and `getGeneratedTestDirectories()` methods are removed from the `IdeaContentRoot` interface.
Clients should replace these invocations with `getSourceDirectories()` and `getTestDirectories()` and use the `isGenerated()` method on the returned instances.

[[locking_single]]
=== Dependency locking now defaults to a single file per project

The format of the dependency lockfile has been changed and as a consequence there is only one file per project instead of one file per configuration per project.
This change only affects _writing_ lock files.
Gradle remains capable of _loading_ lock state saved in the older format.

Head over to <<dependency_locking.adoc#migrate_single_lockfile,the documentation>> to learn how to migrate to the new format.
The migration can be performed per configuration and does not have to be done in a single step.
Gradle will automatically clean up previous lock files when migrating them over to the new file format.

=== Gradle Module Metadata is now reproducible by default

The `buildId` field will not be populated by default to ensure that the produced metadata file remains unchanged when no build inputs are changed.
Users can still opt in to have this unique identifier part of the produced metadata if they want to, see <<publishing_gradle_module_metadata.adoc#sub:gmm-reproducible,the documentation>>.

[[jcenter_deprecation]]
=== The `jcenter()` convenience method is now deprecated

JFrog link:https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter[announced] the sunset of the JCenter repository in February 2021. https://blog.gradle.org/jcenter-shutdown[Many Gradle builds] rely on JCenter for project dependencies.

No new packages or versions are published to JCenter, but JFrog says they will keep JCenter running in a read-only state indefinitely.
We recommend that you consider <<declaring_repositories.adoc#declaring-repositories,using>> `mavenCentral()`, `google()` or a private `maven` repository instead.

Gradle emits a deprecation warning when `jcenter()` is used as a repository and this method is scheduled to be removed in Gradle 8.0.

=== Potential breaking changes

==== Updates to bundled Gradle dependencies

- Kotlin has been updated to https://kotlinlang.org/docs/reference/whatsnew1430.html[Kotlin 1.4.31].
- Groovy has been updated to https://groovy-lang.org/releasenotes/groovy-3.0.html[Groovy 3.0.7].

==== Changes to Groovy and Groovy DSL

Due to the update to the next major version of Groovy, you may experience minor issues when upgrading to Gradle 7.0.

The new version of Groovy has a stricter parser that fails to compile code that may have been accepted in previous Groovy versions.
If you encounter syntax errors, check the https://groovy.apache.org/#reporting-issues[Groovy issue tracker] and https://blogs.apache.org/groovy/entry/groovy-3-highlights[Groovy 3 release highlights].

https://issues.apache.org/jira/browse/GROOVY-9936[Some very specific regressions] have already been fixed in the next minor version of Groovy.

===== Groovy modularization

Gradle no longer embeds a copy of `groovy-all` that bundles all Groovy modules into a single jar--only the most important modules are distributed in the Gradle distribution.

The `localGroovy()` dependency will include these Groovy modules:

- `groovy`
- `groovy-ant`
- `groovy-astbuilder`
- `groovy-console`
- `groovy-datetime`
- `groovy-dateutil`
- `groovy-groovydoc`
- `groovy-json`
- `groovy-nio`
- `groovy-sql`
- `groovy-templates`
- `groovy-test`
- `groovy-xml`

But the following Groovy modules are *not* included:

- `groovy-cli-picocli`
- `groovy-docgenerator`
- `groovy-groovysh`
- `groovy-jmx`
- `groovy-jsr223`
- `groovy-macro`
- `groovy-servlet`
- `groovy-swing`
- `groovy-test-junit5`
- `groovy-testng`

You can pull these dependencies into your build like any other external dependency.

===== Building Gradle plugins with Groovy 3

Plugins built with Gradle 7.0 will now have Groovy 3 on their classpath when using `gradleApi()` or `localGroovy()`.

NOTE: If you use https://spockframework.org/[Spock] to test your plugins, you will need to use Spock 2.x. There are no compatible versions of Spock 1.x and Groovy 3.

```
dependencies {
    // Ensure you use the Groovy 3.x variant
    testImplementation('org.spockframework:spock-core:2.0-groovy-3.0') {
        exclude group: 'org.codehaus.groovy'
    }
}

// Spock 2 is based on JUnit Platform which needs to be enabled explicitly.
tasks.withType(Test).configureEach {
    useJUnitPlatform()
}
```

===== Performance

Depending on the number of subprojects and Groovy DSL build scripts, you may notice a performance regression when compiling build scripts for the first time or when changes are made to the build script's classpath.
This is due to the slower performance of the Groovy 3 parser, but the Groovy team is aware of the issue and trying to mitigate the regression.

In general, we are also looking at how we can improve the performance of build script compilation for both Groovy DSL and Kotlin DSL.

===== Encountering 'Could not find method X for arguments Y on DefaultDependencyHandler'

While the following error initially looks like a compile error, it is actually due to the fact that specific `Configuration`s have been removed.
Please refer to <<sec:configuration_removal>> for more details.

```
Could not find method testCompile() for arguments [DefaultExternalModuleDependency{group='org.junit', name='junit-bom', version='5.7.0', configuration='default'}] on object of type org.gradle.api.internal.artifacts.dsl.dependencies.DefaultDependencyHandler.
```

==== Updates to default tool integration versions

- PMD has been updated to https://github.com/pmd/pmd/releases/tag/pmd_releases%2F6.31.0[PMD 6.31.0].
- Groovy and GroovyDoc have been updated to https://groovy-lang.org/releasenotes/groovy-3.0.html[Groovy 3.0.7].

[[sec:configuration_removal]]
==== Removal of `compile` and `runtime` configurations

Since its inception, Gradle provided the `compile` and `runtime` configurations to declare dependencies.
These however did not support a fine grained scoping of dependencies. Hence, better replacements were introduced in Gradle 3.4:

- The `implementation` configuration should be used to declare dependencies which are _implementation details_ of a library: they are not visible to consumers of the library during compilation time.
- The `api` configuration, available only if you apply the `java-library` plugin, should be used to declare dependencies which are part of the API of a library, that need to be exposed to consumers at compilation time.

In Gradle 7, both the `compile` and `runtime` configurations are removed.
Therefore, you have to migrate to the `implementation` and `api` configurations above.
If you are still using the `java` plugin for a Java library, you will need to apply the `java-library` plugin instead.


.Common configuration upgrades
|===
|Removed Configuration | New Configuration

|`compile`
|`api` or `implementation`

|`runtime`
|`runtimeOnly`

|`testRuntime`
|`testRuntimeOnly`

|`testCompile`
|`testImplementation`


|`<sourceSet>Runtime`
|`<sourceSet>RuntimeOnly`

|`<sourceSet>Compile`
|`<sourceSet>Implementation`
|===

You can find more details about the benefits of the new configurations and which one to use in place of `compile` and `runtime` by reading the <<java_library_plugin.adoc#java_library_plugin,Java Library plugin>> documentation.

[WARNING]
====
When using the Groovy DSL, you need to watch out for a particular upgrade problem when dealing with the removed configurations.

If you were creating custom configurations that extend one of the removed configurations, Gradle may silently create configurations that do not exist.

This looks something like:
```
configurations {
  // This silently creates a configuration called "runtime"
  myConf extendsFrom runtime
}
```

The result of dependency resolution for your custom configuration may not be the same as Gradle 6.x or before.
You may notice missing dependencies or artifacts.
====

==== Location of temporary project files for `ProjectBuilder`

The `ProjectBuilder` API is used for inspecting Gradle builds in unit tests. This API used to create temporary project files under the system temporary directory as defined by `java.io.tmpdir`.

The API now creates temporary project files under the `Test` task's temporary directory. This path is usually under the project build directory.
This may cause test failures when the test expects particular file paths.

If the test uses `ProjectBuilder.withProjectDir(...)`, it is unaffected.

==== Location of temporary files for TestKit tests

Tests that use the <<test_kit#test_kit, TestKit>> API used to create temporary files under the system temporary directory as defined by `java.io.tmpdir`.
These files were used to store copies of Gradle distributions or another test-only Gradle User Home.

TestKit tests will now create temporary files under the `Test` task's temporary directory.
This path is usually under the project build directory.
This may cause test failures when the test expects particular file paths.

If the test uses `GradleRunner.withTestKitDir(...)`, it is unaffected.

==== File system watching with TestKit on Windows

The file system watching implementation on Windows adds a lock to the root project directory in order to watch for changes.
This may cause errors when you try to delete the root project directory after running a build with TestKit.
For example, tests that use TestKit together with JUnit's `@TempDir` extension, or the `TemporaryFolder` rule can run into this problem.
To avoid problems with these file locks, `<<test_kit#test_kit,TestKit>>` disables file system watching for builds executed on Windows via `GradleRunner`.
If you'd like to override the default behavior, you can enable file system watching by passing `--watch-fs` to `GradleRunner.withArguments()`.

==== Removal of the legacy `maven` plugin

The `maven` plugin has been removed.
You should use the `maven-publish` plugin instead.

Please refer to the <<publishing_maven.adoc#publishing_maven, documentation of the Maven Publish plugin>> for more details.

==== Removal of the `uploadArchives` task

The `uploadArchives` task was used in combination with the legacy Ivy or Maven publishing mechanisms.
It has been removed in Gradle 7.
You should migrate to the `maven-publish` or `ivy-publish` plugin instead.

Please refer to the <<publishing_maven.adoc#publishing_maven, documentation of the Maven Publish plugin>> for publishing on Maven repositories.
Please refer to the <<publishing_ivy.adoc#publishing_ivy, documentation of the Ivy Publish plugin>> for publishing on Ivy repositories.

==== Changes in dependency version sorting

In the context of dependency version sorting, a `-SNAPSHOT` version is now considered to be right before a final release but after any `-RC` version.
More special version suffixes are also taken into account.
This brings the Gradle algorithm closer to the Maven one for well-known version suffixes.

Have a look at <<single_versions.adoc#single-version-declarations,the documentation>> for all the rules Gradle applies.

==== Removal of Play Framework plugins

The deprecated Play plugins have been removed.
An external replacement, the link:https://gradle.github.io/playframework[Play Framework plugin], is available from the plugin portal.

=== Removal of deprecated JVM plugins

These unmaintained alternative JVM plugins have been removed:
`java-lang`, `scala-lang`, `junit-test-suite`, `jvm-component`, `jvm-resources`.

Please use the stable <<java_library_plugin.adoc#java_library_plugin,Java Library>> and <<scala_plugin.adoc#scala_plugin,Scala>> plugins instead.

==== Removal of experimental JavaScript plugins

The following plugins for experimental JavaScript integration are now removed from the distribution:
`coffeescript-base`, `envjs`, `javascript-base`, `jshint`, `rhino`.

If you used these plugins despite their experimental nature, you may find suitable replacements in the https://plugins.gradle.org/[Plugin Portal].

==== Configuring the layout of an Ivy repository

The `layout` method taking a configuration block has been removed and is replaced by link:{groovyDslPath}/org.gradle.api.artifacts.repositories.IvyArtifactRepository.html#org.gradle.api.artifacts.repositories.IvyArtifactRepository:patternLayout(org.gradle.api.Action)[patternLayout].

==== Executing a Gradle build without a settings file is now an error

A Gradle build is defined by its `settings.gradle(.kts)` file found in the current or parent directory.
Without a settings file, a Gradle build is undefined and Gradle produces an error when attempting to execute tasks.

To fix this error, <<organizing_gradle_projects.adoc#sec:settings_file,create a `settings.gradle(.kts)` file>> for the build.

Exceptions to this are invoking Gradle with the `init` task or using diagnostic command line flags, such as `--version`.

==== Calling Project.afterEvaluate() after project evaluation is now an error

Gradle 6.x warns users about the wrong behavior and ignores the target action in this scenario.
Starting from 7.0 the same case will produce an error. Plugins and build scripts should be adjusted to call `afterEvaluate` only at configuration time.
If you have such a build failure and the related `afterEvaluate` statement is declared in your build sources then you can simply delete it.
If `afterEvaluate` is declared in a plugin then report the issue to the plugin maintainers.

=== Modifying file collections after values finalized is now an error

Calling any mutator methods (i.e. `clear()`, `add()`, `remove()`, etc.) on `ConfigurableFileCollection` after the stored value calculated throws an exception.
Users and plugin authors should adjust their code such that all configuration on `ConfigurableFileCollection` happens during configuration time, before the values are read.

==== Removal of `ProjectLayout#configurableFiles`

Please use `ObjectFactory#fileCollection()` instead.

==== Removal of `BasePluginConvention.libsDir` and `BasePluginConvention.distsDir`

Please use the `libsDirectory` and `distsDirectory` properties instead.

==== Removal of `UnableToDeleteFileException`

Existing usages should be replaced with `RuntimeException`.

==== Properties removed in Checkstyle and PMD plugins

* The `configDir` getters and setters have been removed from the Checkstle task and extension.
Use the `configDirectory` property instead.
* The `rulePriority` getter and setter have been removed from the Pmd task and extension.
Use the `rulesMinimumPriority` property instead.

==== Removal of `baseName` property in `distribution` plugin

The `getBaseName()` and `setBaseName()` methods were removed from the `Distribution` class. Clients should replace the usages with the `distributionBaseName` property.

==== Using `AbstractTask`

Registering a task with the `AbstractTask` type or with a type extending `AbstractTask` was deprecated in Gradle 6.5 and is now an error in Gradle 7.0.
You can use link:{javadocPath}/org/gradle/api/DefaultTask.html[DefaultTask] instead.

==== Removal of `BuildListener.buildStarted(Gradle)`

`BuildListener.buildStarted(Gradle)` was deprecated in Gradle 6.0 and is now removed in Gradle 7.0.
Please use link:{javadocPath}/org/gradle/BuildListener.html#beforeSettings-org.gradle.api.initialization.Settings-[BuildListener.beforeSettings(Settings)] instead.

==== Removal of unused `StartParameter` APIs

The following APIs, which were not usable via command line options anymore since Gradle 5.0, are now removed:
`StartParameter.useEmptySettings()`, `StartParameter.isUseEmptySettings()`, `StartParameter.setSearchUpwards(boolean)` and `StartParameter.isSearchUpwards()`.

==== Removal of searching for settings files in 'master' directories

Gradle no longer supports discovering the settings file in a directory named `master` in a sibling directory.
If your build still uses this deprecated feature, consider refactoring the build to have the root directory match the physical root of the project hierarchy.
You can find more information about <<multi_project_builds.adoc#multi_project_builds,how to structure a Gradle build>> or a <<structuring_software_products.adoc#structure_large_projects,composition of builds>> in the user manual.
Alternatively, you can still run tasks in builds like this by invoking the build from the `master` directory only using a
<<intro_multi_project_builds.adoc#sec:executing_tasks_by_fully_qualified_name,fully qualified path to the task>>.

==== `modularity.inferModulePath` defaults to 'true'

<<java_library_plugin.adoc#sec:java_library_modular,Compiling>>,
<<java_testing.adoc#sec:java_testing_modular,testing>> and
<<application_plugin.adoc#sec:application_modular,executing>>
now works automatically for any source set that defines a module by containing a `module-info.java` file.
Usually, this is the behavior you need.
If this is causing issues in cases you manually configure the module path, or use a 3rd party plugin for it, you can still opt out of this by setting `modularity.inferModulePath` to `false` on the java extension or individual tasks.

==== Removal of `ValidateTaskProperties`

The `ValidateTaskProperties` task has been removed and replaced by the link:{javadocPath}/org/gradle/plugin/devel/tasks/ValidatePlugins.html[ValidatePlugins] task.

==== Removal of `ImmutableFileCollection`

The `ImmutableFileCollection` type has been removed.
Use the link:{javadocPath}/org/gradle/api/file/ProjectLayout.html#files-java.lang.Object...-[factory method] instead.
A handle to the project layout can be obtained via link:{javadocPath}/org/gradle/api/Project.html#getLayout--[Project.layout].

==== Removal of `ComponentSelectionReason.getDescription`

The method `ComponentSelectionReason.getDescription` has been removed.
It is replaced by `ComponentSelectionReason.getDescriptions` which returns a list of `ComponentSelectionDescriptor`, each having a `getDescription`.

==== Removal of domain object collection constructors

The following deprecated constructors were removed:

- DefaultNamedDomainObjectList(Class, Instantiator, Namer)
- DefaultNamedDomainObjectSet(Class, Instantiator)
- DefaultPolymorphicDomainObjectContainer(Class, Instantiator)
- FactoryNamedDomainObjectContainer(Class, Instantiator, NamedDomainObjectFactory)

==== Removal of arbitrary local cache configuration

The local build cache configuration now needs to be done via link:{javadocPath}/org/gradle/caching/configuration/BuildCacheConfiguration.html#local-org.gradle.api.Action-[BuildCacheConfiguration.local()].

==== Removal of DefaultVersionSelectorScheme constructor

This internal API was used in plugins, amongst other the https://github.com/nebula-plugins[Nebula plugins], and was deprecated in the Gradle 5.x timeline and is now removed.
Latest plugins version should no longer reference it.

==== Setting the `config_loc` config property on the `checkstyle` plugin is now an error

The `checkstyle` plugin now fails for the following configuration
```
checkstyle {
    configProperties['config_loc'] = file("path/to/checkstyle-config-dir")
}
```
Builds should declare the checkstyle configuration with the `checkstyle` block:
```
checkstyle {
    configDirectory = file("path/to/checkstyle-config-dir")
}
```

==== Querying the mapped value of a provider before the producer has completed is now an error

Gradle 6.x warns users about the wrong behavior and then returns a possibly incorrect provider value.
Starting with 7.0 the same case will produce an error.
Plugins and build scripts should be adjusted to query the mapped value of a provider, for example a task output property, after the task has completed.

==== Task validation problems are now errors

Gradle 6.0 started warning about problems with task definitions (such as incorrectly defined inputs or outputs).
For Gradle 7.0, those warnings are now errors and will fail the build.

==== Change in behavior when there's a strict version conflict with a local project

Previous Gradle releases had an inconsistent behavior in regard to conflict resolution in a particular configuration:
- your project declares a strict dependency on a published module (for example, `com.mycompany:some-module:1.2!!`, where `1.2!!` is the short hand notation for a strict dependency on 1.2)
- your build actually provides `com.mycompany:some-module` in a higher version

Previous Gradle releases would succeed, selecting the project dependency despite the strict constraint.
Starting from Gradle 7, this will trigger a dependency resolution failure.

See https://github.com/gradle/gradle/issues/16706[this issue] for more context.

=== Deprecations

[[missing_dependencies]]
==== Missing dependencies between tasks

Having a task which produces an output in a location and another task consuming that location by referring to it as an input without the consumer task depending on the producer task has been deprecated.
A fix for this problem is to <<incremental_build.adoc#sec:link_output_dir_to_input_files,add a dependency from the consumer to the producer>>.

[[duplicates-strategy]]
==== Duplicates strategy

Gradle 7 now fails when a copy operation (or any operation which uses a `org.gradle.api.file.CopySpec`) encounters a duplicate entry, and that the duplicates strategy isn't set.
Please look at link:{javadocPath}/org/gradle/api/file/CopySpec.html#setDuplicatesStrategy-org.gradle.api.file.DuplicatesStrategy-[the CopySpec docs] for details.

[[changes_6.9]]
== Upgrading from 6.8 and earlier

No upgrade notes from 6.8 to 6.9, as 6.9 only contains bug fixes.

[[changes_6.8]]
== Upgrading from 6.7 and earlier

=== Potential breaking changes

==== Toolchain API is now marked as @NonNull

The API supporting the Java Toolchain feature in `org.gradle.jvm.toolchain` is now marked as `@NonNull`.

This may impact Kotlin consumers where the return types of APIs are no longer nullable.

==== Updates to default tool integration versions

- JaCoCo has been updated to http://www.jacoco.org/jacoco/trunk/doc/changes.html[0.8.6].
- Checkstyle has been updated to https://checkstyle.sourceforge.io/releasenotes.html#Release_8.37[Checkstyle 8.37].
- CodeNarc has been updated to https://github.com/CodeNarc/CodeNarc/blob/v2.0.0/CHANGELOG.md[CodeNarc 2.0.0].

==== Updates to bundled Gradle dependencies

- Kotlin has been updated to https://blog.jetbrains.com/kotlin/2020/08/kotlin-1-4-released-with-a-focus-on-quality-and-performance/[Kotlin 1.4.20].
  Note that Gradle scripts are still using the Kotlin 1.3 language.
- Apache Ant has been updated to 1.10.9 to fix https://github.com/gradle/gradle/security/advisories/GHSA-j45w-qrgf-25vm[CVE-2020-11979]

==== Projects imported into Eclipse now include custom source set classpaths

Previously, projects imported by Eclipse only included dependencies for the main and test source sets.
The compile and runtime classpaths of custom source sets were ignored.

Since Gradle 6.8, projects imported into Eclipse include the compile and runtime classpath for every source set defined by the build.

==== SourceTask is no longer sensitive to empty directories

Previously, empty directories would be taken into account during up-to-date checks and build cache key calculations for the sources declared in `SourceTask`.
This meant that a source tree that contained an empty directory and an otherwise identical source tree that did not contain the empty directory would be considered different sources, even if the task would produce the same outputs.
In Gradle 6.8, `SourceTask` now ignores empty directories during doing up-to-date checks and build cache key calculations.
In the vast majority of cases, this is the desired behavior, but it is possible that a task may extend `SourceTask` but also produce different outputs when empty directories are present in the sources.
For tasks where this is a concern, you can expose a separate property without the `@IgnoreEmptyDirectories` annotation in order to capture those changes:

```
@InputFiles
@SkipWhenEmpty
@PathSensitive(PathSensitivity.ABSOLUTE)
public FileTree getSourcesWithEmptyDirectories() {
    return super.getSource()
}
```

==== Changes to publications

Publishing a component which has a dependency on an enforced platform now triggers a validation error, preventing accidental publishing of bad metadata:
enforced platforms use cases should be limited to applications, not things which can be consumed from another library or an application.

If, for some reason, you still want to publish components with dependencies on enforced platforms, you can disable the validation following the <<publishing_setup.adoc#sec:suppressing_validation_errors, documentation>>.

==== Changing default excludes during the execution phase

Gradle's file trees apply some default exclude patterns for convenience — the same defaults as Ant in fact.
See the <<working_with_files.adoc#sec:file_trees,user manual>> for more information.
Sometimes, Ant's default excludes prove problematic, for example when you want to include the `.gitignore` in an archive file.

Changing Gradle's default excludes during the execution phase can lead to correctness problems with up-to-date checks.
As a consequence, you are only allowed to change Gradle's default excludes in the settings script, see the <<working_with_files.adoc#sec:change_default_excludes,user manual>> for an example.

=== Deprecations

[[referencing_tasks_from_included_builds]]
==== Referencing tasks from included builds

Direct references to tasks from included builds in `mustRunAfter`, `shouldRunAfter` and `finalizedBy` task methods have been deprecated.
Task ordering using `mustRunAfter` and `shouldRunAfter` as well as finalizers specified by `finalizedBy` should be used for task ordering within a build.
If you happen to have cross-build task ordering defined using above mentioned methods, consider restructuring such builds and decoupling them from one another.

[[master_subdirectory_root_build]]
==== Searching for settings files in 'master' directories

Gradle will emit a deprecation warning when your build relies on finding the settings file in a directory named `master` in a sibling directory.

If your build uses this feature, consider refactoring the build to have the root directory match the physical root of the project hierarchy.

Alternatively, you can still run tasks in builds like this by invoking the build from the `master` directory only using a
<<intro_multi_project_builds.adoc#sec:executing_tasks_by_fully_qualified_name,fully qualified path to the task>>.

[[using_NamedDomainObjectContainer_invoke_kotlin_Function1]]
==== Using method `NamedDomainObjectContainer<T>.invoke(kotlin.Function1)`

Gradle Kotlin DSL extensions have been changed to favor Gradle's `Action<T>` type over Kotlin function types.

While the change should be transparent to Kotlin clients, Java clients calling Kotlin DSL extensions need to be updated to use the `Action<T>` APIs.

[[changes_6.7]]
== Upgrading from 6.6 and earlier

=== Potential breaking changes

==== buildSrc can now see included builds from the root

Previously, `buildSrc` was built in such a way that included builds were ignored from the root build.

Since Gradle 6.7, `buildSrc` can see any included build from the root build.
This may cause dependencies to be substituted from an included build in `buildSrc`.
This may also change the order in which some builds are executed if an included build is needed by `buildSrc`.

==== Updates to default tool integration versions

- PMD has been updated to https://github.com/pmd/pmd/releases/tag/pmd_releases%2F6.26.0[PMD 6.26.0].
- Checkstyle has been updated to https://checkstyle.sourceforge.io/releasenotes.html#Release_8.35[Checkstyle 8.35].
- CodeNarc has been updated to https://github.com/CodeNarc/CodeNarc/blob/v1.6.1/CHANGELOG.md[CodeNarc 1.6.1].

=== Deprecations

==== Changing default excludes during the execution phase

Gradle's file trees apply some default exclude patterns for convenience — the same defaults as Ant in fact.
See the <<working_with_files.adoc#sec:file_trees,user manual>> for more information.
Sometimes, Ant's default excludes prove problematic, for example when you want to include the `.gitignore` in an archive file.

Changing Gradle's default excludes during the execution phase can lead to correctness problems with up-to-date checks, and is deprecated.
You are only allowed to change Gradle's default excludes in the settings script, see the <<working_with_files.adoc#sec:change_default_excludes,user manual>> for an example.

==== Using a Configuration directly as a dependency

Gradle allowed instances of `Configuration` to be used directly as dependencies:

```
dependencies {
    implementation(configurations.myConfiguration)
}
```

This behavior is now deprecated as it is confusing: one could expect the "dependent configuration" to be resolved first and add the result of resolution as dependencies to the including configuration, which is not the case.
The deprecated version can be replaced with the actual behavior, which is configuration inheritance:

```
configurations.implementation.extendsFrom(configurations.myConfiguration)
```


[[changes_6.6]]
== Upgrading from 6.5 and earlier

=== Potential breaking changes

==== Updates to bundled Gradle dependencies

- Ant has been updated to https://downloads.apache.org/ant/RELEASE-NOTES-1.10.8.html[1.10.8].
- Groovy has been updated to https://groovy-lang.org/changelogs/changelog-2.5.12.html[Groovy 2.5.12].

==== Dependency substitutions and variant aware dependency resolution

While adding support for expressing <<resolution_rules#sec:variant_aware_substitutions, variant support>> in dependency substitutions, a bug fix introduced a behaviour change that some builds may rely upon.
Previously a substituted dependency would still use the <<variant_attributes#variant_attributes, attributes>> of the original selector instead of the ones from the replacement selector.

With that change, existing substitutions around dependencies with richer selectors, such as for platform dependencies, will no longer work as they did.
It becomes mandatory to define the variant aware part in the target selector.

You can be affected by this change if you:

* have dependencies on platforms, like `implementation platform("org:platform:1.0")`
* _or_ if you specify attributes on dependencies,
* _and_ you use <<resolution_rules#resolution_rules, resolution rules>> on these dependencies.

See the <<resolution_rules#sec:variant_aware_substitutions, documentation>> for resolving issues if you are impacted.

=== Deprecations

No deprecations were made in Gradle 6.6.

[[changes_6.5]]
== Upgrading from 6.4 and earlier

=== Potential breaking changes

==== Updates to bundled Gradle dependencies

- Kotlin has been updated to https://github.com/JetBrains/kotlin/releases/tag/v1.3.72[Kotlin 1.3.72].
- Groovy has been updated to https://groovy-lang.org/changelogs/changelog-2.5.11.html[Groovy 2.5.11].

==== Updates to default tool integration versions

- PMD has been updated to https://github.com/pmd/pmd/releases/tag/pmd_releases%2F6.23.0[PMD 6.23.0].

=== Deprecations

[[abstract_task_deprecated]]
==== Internal class AbstractTask is deprecated

`AbstractTask` is an internal class which is visible on the public API, as a superclass of public type `DefaultTask`.
`AbstractTask` will be removed in Gradle 7.0, and the following are deprecated in Gradle 6.5:

- Registering a task whose type is `AbstractTask` or `TaskInternal`. You can remove the task type from the task registration and Gradle will use `DefaultTask` instead.
- Registering a task whose type is a subclass of `AbstractTask` but not a subclass of `DefaultTask`. You can change the task type to extend `DefaultTask` instead.
- Using the class `AbstractTask` from plugin code or build scripts. You can change the code to use `DefaultTask` instead.

[[changes_6.4]]
== Upgrading from 6.3 and earlier

=== Potential breaking changes

[[upgrade:pmd_expects_6]]
==== PMD plugin expects PMD 6.0.0 or higher by default

Gradle 6.4 enabled incremental analysis by default.
Incremental analysis is only available in PMD 6.0.0 or higher.
If you want to use an older PMD version, you need to disable incremental analysis:

```
pmd {
    incrementalAnalysis = false
}
```

==== Changes in dependency locking

With Gradle 6.4, the incubating API for <<dependency_locking#fine_tuning_dependency_locking_behaviour_with_lock_mode, dependency locking `LockMode`>> has changed.
The value is now set via a `Property<LockMode>` instead of a direct setter.
This means that the notation to set the value has to be updated for the Kotlin DSL:

```
dependencyLocking {
    lockMode.set(LockMode.STRICT)
}
```

Users of the Groovy DSL should not be impacted as the notation `lockMode = LockMode.STRICT` remains valid.

==== Java versions in published metadata

If a Java library is published with Gradle Module Metadata, the information which Java version it supports is encoded in the `org.gradle.jvm.version` attribute.
By default, this attribute was set to what you configured in `java.targetCompatibility`.
If that was not configured, it was set to the current Java version running Gradle.
Changing the version of a particular compile task, e.g. `javaCompile.targetCompatibility` had no effect on that attribute, leading to wrong information if the attribute was not adjusted manually.
This is now fixed and the attribute defaults to the setting of the compile task that is associated with the sources from which the published jar is built.

==== Ivy repositories with custom layouts

Gradle versions from 6.0 to 6.3.x included could generate bad Gradle Module Metadata when publishing on an Ivy repository which had a custom repository layout.
Starting from 6.4, Gradle will no longer publish Gradle Module Metadata if it detects that you are using a custom repository layout.

==== New properties may shadow variables in build scripts

This release introduces some new properties -- `mainClass`, `mainModule`, `modularity` -- in different places.
Since these are very generic names, there is a chance that you use one of them in your build scripts as variable name.
A new property might then shadow one of your variables in an undesired way, leading to a build failure where the property is accessed instead of the local variable with the same name.
You can fix it by renaming the corresponding variable in the build script.

Affected is configuration code inside the `application {}` and `java {}` configuration blocks, inside a java execution setup with `project.javaexec {}`, and inside various task configurations
(`JavaExec`, `CreateStartScripts`, `JavaCompile`, `Test`, `Javadoc`).

==== Updates to bundled Gradle dependencies

- Kotlin has been updated to https://github.com/JetBrains/kotlin/releases/tag/v1.3.71[Kotlin 1.3.71].

=== Deprecations

There were no deprecations between Gradle 6.3 and 6.4.

[[changes_6.3]]
== Upgrading from 6.2 and earlier

=== Potential breaking changes

==== Fewer dependencies available in IDEA

Gradle no longer includes the annotation processor classpath as provided dependencies in IDEA.
The dependencies IDEA sees at compile time are the same as what Gradle sees after resolving the compile classpath (configuration named `compileClasspath`).
This prevents the leakage of annotation processor dependencies into the project's code.

Before Gradle introduced <<java_plugin.adoc#sec:incremental_annotation_processing,incremental annotation processing support>>, IDEA required all annotation processors to be on the compilation classpath to be able to run annotation processing when compiling in IDEA.
This is no longer necessary because Gradle has a separate <<java_plugin.adoc#tab:configurations,annotation processor classpath>>.
The dependencies for annotation processors are not added to an IDEA module's classpath when a Gradle project with annotation processors is imported.

==== Updates to bundled Gradle dependencies

- Kotlin has been updated to https://blog.jetbrains.com/kotlin/2020/03/kotlin-1-3-70-released/[Kotlin 1.3.70].
- Groovy has been updated to http://groovy-lang.org/changelogs/changelog-2.5.10.html[Groovy 2.5.10].

==== Updates to default tool integration versions

- PMD has been updated to https://pmd.github.io/pmd-6.21.0/pmd_release_notes.html#24-january-2020---6210[PMD 6.21.0].
- CodeNarc has been updated to https://github.com/CodeNarc/CodeNarc/blob/v1.5/CHANGELOG.md#version-15----nov-2019[CodeNarc 1.5].

==== Rich console support removed for some 32-bit operating systems

Gradle 6.3 does not support the <<command_line_interface.adoc#sec:rich_console, rich console>> for 32-bit Unix systems and for old FreeBSD versions (older than FreeBSD 10). Microsoft Windows 32-bit is unaffected.

Gradle will continue building projects on 32-bit systems but will no longer show the rich console.

=== Deprecations

==== Using default and archives configurations

Almost every Gradle project has the _default_ and _archives_ configurations which are added by the _base_ plugin.
These configurations are no longer used in modern Gradle builds that use <<variant_model.adoc#understanding-variant-selection,variant aware dependency management>> and the <<publishing_setup.adoc#publishing_components,new publishing plugins>>.

While the configurations will stay in Gradle for backwards compatibility for now, using them to declare dependencies or to resolve dependencies is now deprecated.

Resolving these configurations was never an intended use case and only possible because in earlier Gradle versions _every_ configuration was resolvable.
For declaring dependencies, please use the configurations provided by the plugins you use, for example by the <<java_library_plugin.adoc#sec:java_library_configurations_graph,Java Library plugin>>.

[[changes_6.2]]
== Upgrading from 6.1 and earlier

=== Potential breaking changes

==== Compile and runtime classpath now request library variants by default

A classpath in a JVM project now explicitly requests the `org.gradle.category=library` attribute.
This leads to clearer error messages if a certain library cannot be used.
For example, when the library does not support the required Java version.
The practical effect is that now all <<java_platform_plugin.adoc#sec:java_platform_consumption,platform dependencies>> have to be declared as such.
Before, platform dependencies also worked, accidentally, when the `platform()` keyword was omitted for local platforms or platforms published with Gradle Module Metadata.

==== Properties from project root `gradle.properties` leaking into `buildSrc` and included builds

There was a regression in Gradle 6.2 and Gradle 6.2.1 that caused Gradle properties set in the project root `gradle.properties` file to leak into the `buildSrc` build and any builds included by the root.

This could cause your build to start failing if the `buildSrc` build or an included build suddenly found an unexpected or incompatible value for a property coming from the project root `gradle.properties` file.

The regression has been fixed in Gradle 6.2.2.

=== Deprecations

There were no deprecations between Gradle 6.1 and 6.2.

[[changes_6.1]]
== Upgrading from 6.0 and earlier

=== Deprecations

==== Querying a mapped output property of a task before the task has completed

Querying the value of a mapped output property before the task has completed can cause strange build failures because it indicates stale or non-existent outputs may be used by mistake.
This behavior is deprecated and will emit a deprecation warning. This will become an error in Gradle 7.0.

The following example demonstrates this problem where the Producer's output file is parsed before the Producer executes:
```
class Consumer extends DefaultTask {
    @Input
    final Property<Integer> threadPoolSize = ...
}

class Producer extends DefaultTask {
    @OutputFile
    final RegularFileProperty outputFile = ...
}

// threadPoolSize is read from the producer's outputFile
consumer.threadPoolSize = producer.outputFile.map { it.text.toInteger() }

// Emits deprecation warning
println("thread pool size = " + consumer.threadPoolSize.get())
```

Querying the value of `consumer.threadPoolSize` will produce a deprecation warning if done prior to `producer` completing, as the output file has not yet been generated.

==== Discontinued methods
The following methods have been discontinued and should no longer be used. They will be removed in Gradle 7.0.

- `BasePluginConvention.setProject(ProjectInternal)`
- `BasePluginConvention.getProject()`
- `StartParameter.useEmptySettings()`
- `StartParameter.isUseEmptySettings()`

[[upgrading_jvm_plugins]]
==== Alternative JVM plugins (a.k.a "Software Model")

A set of alternative plugins for Java and Scala development were introduced in Gradle 2.x as an experiment based on the "software model".
These plugins are now deprecated and will eventually be removed.
If you are still using one of these old plugins (`java-lang`, `scala-lang`, `jvm-component`, `jvm-resources`, `junit-test-suite`) please consult the documentation on <<building_java_projects.adoc#building_java_projects,Building Java & JVM projects>> to determine which of the stable JVM plugins are appropriate for your project.

=== Potential breaking changes

==== `ProjectLayout` is no longer available to worker actions as a service

In Gradle 6.0, the `ProjectLayout` service was made available to worker actions via service injection.
This service allowed for mutable state to leak into a worker action and introduced a way for dependencies to go undeclared in the worker action.

`ProjectLayout` has been removed from the available services.  Worker actions that were using `ProjectLayout` should switch to injecting the `projectDirectory` or `buildDirectory` as a parameter instead.

==== Updates to bundled Gradle dependencies

- Kotlin has been updated to https://blog.jetbrains.com/kotlin/2019/11/kotlin-1-3-60-released/[Kotlin 1.3.61].

==== Updates to default tool integration versions

- Checkstyle has been updated to https://checkstyle.org/releasenotes.html#Release_8.27[Checkstyle 8.27].
- PMD has been updated to https://pmd.github.io/pmd-6.20.0/pmd_release_notes.html#29-november-2019---6200[PMD 6.20.0].

==== Publishing Spring Boot applications

Starting from Gradle 6.2, Gradle performs a sanity check before uploading, to make sure you don't upload stale files (files produced by another build).
This introduces a problem with Spring Boot applications which are uploaded using the `components.java` component:

```
Artifact my-application-0.0.1-SNAPSHOT.jar wasn't produced by this build.
```

This is caused by the fact that the main `jar` task is disabled by the Spring Boot application, and the component expects it to be present.
Because the `bootJar` task uses the _same file_ as the main `jar` task by default, previous releases of Gradle would either:

- publish a stale `bootJar` artifact
- or fail if the `bootJar` task hasn't been called previously

A workaround is to tell Gradle what to upload.
If you want to upload the `bootJar`, then you need to configure the outgoing configurations to do this:

```
configurations {
   [apiElements, runtimeElements].each {
       it.outgoing.artifacts.removeIf { it.buildDependencies.getDependencies(null).contains(jar) }
       it.outgoing.artifact(bootJar)
   }
}
```

Alternatively, you might want to re-enable the `jar` task, and add the `bootJar` with a different classifier.

```
jar {
   enabled = true
}

bootJar {
   classifier = 'application'
}
```
