<commit_before>// 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 the latest

This chapter provides the information you need to migrate your Gradle 6.x builds to the latest Gradle release. For migrating from Gradle 4.x or 5.x, see 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 could 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 {gradleVersion}` to update the project to {gradleVersion}.
. Try to run the project and debug any errors using the <<troubleshooting.adoc#troubleshooting, Troubleshooting Guide>>.

[[changes_7.0]]
== Upgrading from 6.8
=== 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.

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

=== Potential breaking changes

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

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.

==== 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>> and <<scala_plugin.adoc#,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 undefined builds is now an error

A Gradle build is defined by a `settings.gradle(.kts)` file in the current or parent directory.
Without a settings file, a Gradle build is undefined.
Executing Gradle in such a directory is now an error.

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

==== Removal of `ProjectLayout#configurableFiles`

Please use `ObjectFactory#fileCollection()` instead.

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

Please use the 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#,how to structure a Gradle build>> or a <<structuring_software_products.adoc#,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 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--.

==== 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 the link:{javadocPath}/org/gradle/caching/configuration/BuildCacheConfiguration.html#local-org.gradle.api.Action-.
<commit_msg>Fix broken links in upgrade guide<commit_after>// 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 the latest

This chapter provides the information you need to migrate your Gradle 6.x builds to the latest Gradle release. For migrating from Gradle 4.x or 5.x, see 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 could 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 {gradleVersion}` to update the project to {gradleVersion}.
. Try to run the project and debug any errors using the <<troubleshooting.adoc#troubleshooting, Troubleshooting Guide>>.

[[changes_7.0]]
== Upgrading from 6.8
=== 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.

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

=== Potential breaking changes

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

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.

==== 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>> and <<scala_plugin.adoc#,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 undefined builds is now an error

A Gradle build is defined by a `settings.gradle(.kts)` file in the current or parent directory.
Without a settings file, a Gradle build is undefined.
Executing Gradle in such a directory is now an error.

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

==== Removal of `ProjectLayout#configurableFiles`

Please use `ObjectFactory#fileCollection()` instead.

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

Please use the 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#,how to structure a Gradle build>> or a <<structuring_software_products.adoc#,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].

==== 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 the link:{javadocPath}/org/gradle/caching/configuration/BuildCacheConfiguration.html#local-org.gradle.api.Action-[BuildCacheConfiguration].

{'fraction_non_alphanumeric': 0.07511944788533002, 'fraction_numerical': 0.0034507166873119803, 'mean_word_length': 5.482649842271293, 'pattern_counts': {'":': 0, '<': 67, '<?xml version=': 0, '>': 67, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1566533', 'n_tokens_mistral': 5980, 'n_tokens_neox': 5635, 'n_words': 2660}