Mention new deprecations in upgrade doc

Mention new deprecations in upgrade doc

// 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_5]]
= Upgrading your build from Gradle 5.x to 6.0

This chapter provides the information you need to migrate your Gradle 5.x builds to Gradle 6.0. For migrating from Gradle 4.x, complete the <<upgrading_version_4.adoc#upgrading_version_4, 4.x to 5.0 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_6.0]]
== Upgrading from 5.6 and earlier

=== Deprecations

==== Dependencies should no longer be declared using the compile and runtime configurations

The usage of the `compile` and `runtime` configurations in the Java ecosystem plugins has been discouraged for some time now.
These configurations, and their counterparts in other sources sets (e.g. `testCompile` and `testRuntime`), should not be utilised anymore.
Instead, use the `implementation`, `api`, `compileOnly` and `runtimeOnly` configurations to declare dependencies and the `compileClasspath` and `runtimeClasspath` configurations to resolve dependencies.

==== Local build cache type shouldn't be specified

When configuring the local build cache the use of `BuildCacheConfiguration.local(Class)` and `local(Class, Action)` has now been deprecated; use `getLocal()` or `local(Action)` instead.
These methods now assume the local build cache type to be `DirectoryBuildCache`.

=== Potential breaking changes

==== Local build cache is always a directory cache

In the past it was possible to use any build cache implementation as the `local` cache.
This is not allowed anymore as the local cache is always a `DirectoryBuildCache`.
Calls to `BuildCacheConfiguration.local(Class)` with anything other than `DirectoryBuildCache` as the type will fail the build.
Calling these methods with the `DirectoryBuildCache` type will produce a deprecation warning.
Use `getLocal()` and `local(Action)` instead, respectively.
These methods now assume the local build cache type to be `DirectoryBuildCache`.

==== Failing to pack or unpack cached results will now fail the build

In the past when Gradle encountered a problem while packaging the results of a cached task, it would ignore the problem and try to continue running the build.
Similarly, having encountered a corrupt cached artifact during unpacking Gradle would try to remove whatever was already unpacked of the output and re-execute the task to make sure the build had a chance to succeed.

While this behavior could be helpful to maintain executing build no matter what, hiding the problems this way can lead to reduced cache performance.
In Gradle 6.0 we are switching to failing fast, and both pack and unpack errors will result the build to fail.
Doing so allows these problems to be surfaced more easily.

==== Gradle Module Metadata is always published

[Gradle Module Metadata](https://blog.gradle.org/gradle-metadata-1.0), officially introduced in Gradle 5.3, was created to solve many of the problems that have plagued dependency management for years, in particular, but not exclusively, in the Java ecosystem.
With Gradle 6.0, Gradle Module Metadata is enabled by default.
This means, if you are publishing libraries with Gradle, using the <<publishing_maven.adoc#,maven-publish>> or <<publishing_ivy.adoc#,ivy-publish>> plugin, the Gradle Module Metadata file is always published *in addition* to the traditional metadata.
The traditional metadata file will contain a marker so that Gradle knows that there is additional metadata to consume.

==== Maven or Ivy repositories are no longer queried for artifacts without metadata by default

If Gradle fails to locate the metadata file (`.pom` or `ivy.xml`) of a module in a repository defined in the `repositories { }` section, it now assumes that the module does not exist in that repository.
Previously, Gradle was also looking for a default artifact (`.jar`) which usually also does not exist.
This often caused large number of unnecessary requests when using multiple repositories.
This change speeds up builds with many dependencies using multiple repositories.
You can opt into the previous behavior for selected repositories by adding the `artifact()` <<declaring_repositories.adoc#sec:repository-content-filtering,repository content filter>>.

==== `@Nullable` annotation is gone

The `org.gradle.api.Nullable` annotation type has been removed. Use `javax.annotation.Nullable` from JSR-305 instead.

==== Task validation changes

- `ValidateTaskProperties.setClasses()` is now removed. Use `getClasses().setFrom()` instead.
- `ValidateTaskProperties.setClasspath()` is now removed. use `getClasspath().setFrom()` instead.

==== The FindBugs plugin has been removed

The deprecated FindBugs plugin has been removed.
As an alternative, you can use the link:https://plugins.gradle.org/plugin/com.github.spotbugs[SpotBugs plugin] from the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The JDepend plugin has been removed

The deprecated JDepend plugin has been removed.
There are a number of community-provided plugins for code and architecture analysis available on the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The OSGI plugin has been removed

The deprecated OSGI plugin has been removed.  There are a number of community-provided OSGI plugins available on the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The announce and build-announcements plugins have been removed

The deprecated announce and build-announcements plugins have been removed.  There are a number of community-provided plugins for sending out notifications available on the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The Compare Gradle Builds plugin has been removed

The deprecated Compare Gradle Builds plugin has been removed.
Please use https://scans.gradle.com/[build scans] for build analysis and comparison.

==== Changes to the task container

The following deprecated methods on the task container now result in errors:

- `TaskContainer.add()`
- `TaskContainer.addAll()`
- `TaskContainer.remove()`
- `TaskContainer.removeAll()`
- `TaskContainer.retainAll()`
- `TaskContainer.clear()`
- `TaskContainer.iterator().remove()`

Additionally, the following deprecated functionality now results in an error:

- Replacing a task that has already been realized.
- Replacing a registered (unrealized) task with an incompatible type. A compatible type is the same type or a sub-type of the registered type.
- Replacing a task that has never been registered.

==== Updates to bundled Gradle dependencies

- Groovy has been updated to http://groovy-lang.org/changelogs/changelog-2.5.8.html[Groovy 2.5.8].
- Kotlin has been updated to https://blog.jetbrains.com/kotlin/2019/08/kotlin-1-3-50-released/[Kotlin 1.3.50].

The following breaking changes will appear as deprecation warnings with Gradle 5.6:

Miscellaneous::

* The `org.gradle.util.GUtil.savePropertiesNoDateComment` has been removed. There is no public replacement for this internal method.
* The deprecated class `org.gradle.api.tasks.compile.CompilerArgumentProvider` has been removed.
  Use link:{javadocPath}/org/gradle/process/CommandLineArgumentProvider.html[org.gradle.process.CommandLineArgumentProvider] instead.
* The deprecated class `org.gradle.api.ConventionProperty` has been removed.
  Use link:{javadocPath}/org/gradle/api/provider/Provider.html[Providers] instead of convention properties.
* The deprecated class `org.gradle.reporting.DurationFormatter` has been removed.
* The bridge method `org.gradle.api.tasks.TaskInputs.property(String name, @Nullable Object value)` returning `TaskInputs` has been removed.
  A plugin using the method must be compiled with Gradle 4.3 to work on Gradle 6.0.
* The following setters have been removed from `JacocoReportBase`:
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:executionData[executionData] - use `getExecutionData().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:sourceDirectories[sourceDirectories] - use `getSourceDirectories().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:classDirectories[classDirectories] - use `getClassDirectories().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:additionalClassDirs[additionalClassDirs] - use `getAdditionalClassDirs().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:additionalSourceDirs[additionalSourceDirs] - use `getAdditionalSourceDirs().setFrom()` instead.
* The `append` property on `JacocoTaskExtension` has been removed.
  `append` is now always configured to be true for the Jacoco agent.
* The `configureDefaultOutputPathForJacocoMerge` method on `JacocoPlugin` has been removed.
  The method was never meant to be public.
* File paths in link:{javadocPath}/org/gradle/plugins/ear/descriptor/DeploymentDescriptor.html#getFileName--[deployment descriptor file name] for the ear plugin are not allowed any more.
  Use a simple name, like `application.xml`, instead.
* The `org.gradle.testfixtures.ProjectBuilder` constructor has been removed. Please use `ProjectBuilder.builder()` instead.
* When <<groovy_plugin.adoc#sec:incremental_groovy_compilation,incremental Groovy compilation>> is enabled, a wrong configuration of the source roots or enabling Java annotation for Groovy now fails the build.
  Disable incremental Groovy compilation when you want to compile in those cases.
* `ComponentSelectionRule` no longer can inject the metadata or ivy descriptor.
  Use the methods on the <<declaring_dependency_versions.adoc#sec:component_selection_rules,`ComponentSelection` parameter>> instead.
* Declaring an <<custom_tasks.adoc#incremental_tasks,incremental task>> without declaring outputs is now an error.
  Declare file outputs or use link:{javadocPath}/org/gradle/api/tasks/TaskOutputs.html#upToDateWhen-groovy.lang.Closure-[TaskOutputs.upToDateWhen()] instead.

[[changes_5.6]]
== Upgrading from 5.5 and earlier

=== Deprecations

==== BuildSrc usage in Gradle settings

Access to the buildSrc project and its dependencies in gradle settings scripts is now deprecated.
This is due to plans to make initialization of gradle builds more efficient.

This will become an error in Gradle 6.0.

==== Changing the contents of `ConfigurableFileCollection` task properties after task starts execution

When a task property has type `ConfigurableFileCollection`, then the file collection referenced by the property will ignore changes made to the contents of the collection once the task
starts execution. This has two benefits. Firstly, this prevents accidental changes to the property value during task execution which can cause Gradle up-to-date checks and build cache lookup
using different values to those used by the task action. Secondly, this improves performance as Gradle can calculate the value once and cache the result.

This will become an error in Gradle 6.0.

==== Creating `SignOperation` instances

Creating `SignOperation` instances directly is now deprecated. Instead, the methods of `SigningExtension` should be used to create these instances.

This will become an error in Gradle 6.0.

==== Declaring an incremental task without outputs

Declaring an <<custom_tasks.adoc#incremental_tasks,incremental task>> without declaring outputs is now deprecated.
Declare file outputs or use link:{javadocPath}/org/gradle/api/tasks/TaskOutputs.html#upToDateWhen-groovy.lang.Closure-[TaskOutputs.upToDateWhen()] instead.

This will become an error in Gradle 6.0.

==== `WorkerExecutor.submit()` is deprecated

The `WorkerExecutor.submit()` method is now deprecated.
The new `noIsolation()`, `classLoaderIsolation()` and `processIsolation()` methods should now be used to submit work.
See <<custom_tasks.adoc#using-the-worker-api, the userguide>> for more information on using these methods.

`WorkerExecutor.submit()` will be removed in Gradle 7.0.

=== Potential breaking changes

==== Task dependencies are honored for task `@Input` properties whose value is a `Property`

Previously, task dependencies would be ignored for task `@Input` properties of type `Property<T>`. These are now honored, so that it is possible to attach a task output property to a task `@Input` property.

This may introduce unexpected cycles in the task dependency graph, where the value of an output property is mapped to produce a value for an input property.

==== Declaring task dependencies using a file `Provider` that does not represent a task output

Previously, it was possible to pass `Task.dependsOn()` a `Provider<File>`, `Provider<RegularFile>` or `Provider<Directory>` instance that did not represent a task output. These providers would be silently ignored.

This is now an error because Gradle does not know how to build files that are not task outputs.

*Note* that it is still possible to to pass `Task.dependsOn()` a `Provider` that returns a file and that represents a task output, for example `myTask.dependsOn(jar.archiveFile)` or `myTask.dependsOn(taskProvider.flatMap { it.outputDirectory })`, when the `Provider` is an annotated `@OutputFile` or `@OutputDirectory` property of a task.

==== Setting `Property` value to `null` uses the property convention

Previously, calling `Property.set(null)` would always reset the value of the property to 'not defined'. Now, the convention that is associated with the property using the `convention()` method
will be used to determine the value of the property.

==== Enhanced validation of names for `publishing.publications` and `publishing.repositories`

The repository and publication names are used to construct task names for publishing. It was possible to supply a name that would result in an invalid task name. Names for publications and repositories are now restricted to `[A-Za-z0-9_\\-.]+`.

==== Restricted Worker API classloader and process classpath

Gradle now prevents internal dependencies (like Guava) from leaking into the classpath used by Worker API actions. This fixes link:https://github.com/gradle/gradle/issues/3698[an issue] where a worker needs to use a dependency that is also used by Gradle internally.

In previous releases, it was possible to rely on these leaked classes. Plugins relying on this behavior will now fail.  To fix the plugin, the worker should explicitly include all required dependencies in its classpath.

==== Default PMD version upgraded to 6.15.0

<<pmd_plugin#pmd_plugin, The PMD plugin>> has been upgraded to use link:https://pmd.github.io/pmd-6.15.0/pmd_release_notes.html[PMD version 6.15.0] instead of 6.8.0 by default.

Contributed by link:https://github.com/wreulicke[wreulicke]

==== Configuration copies have unique names

Previously, all copies of a configuration always had the name `<OriginConfigurationName>Copy`. Now when creating multiple copies, each will have a unique name by adding an index starting from the second copy. (e.g. `CompileOnlyCopy2`)

==== Changed classpath filtering for Eclipse

Gradle 5.6 no longer supplies custom classpath attributes in the Eclipse model. Instead, it provides the attributes for link:https://www.eclipse.org/eclipse/news/4.8/jdt.php#jdt-test-sources[Eclipse test sources]. This change requires Buildship version 3.1.1 or later.

==== Embedded Kotlin upgraded to 1.3.41

Gradle Kotlin DSL scripts and Gradle Plugins authored using the `kotlin-dsl` plugin are now compiled using Kotlin 1.3.41.

Please see the Kotlin link:https://blog.jetbrains.com/kotlin/2019/06/kotlin-1-3-40-released/[blog post] and link:https://github.com/JetBrains/kotlin/blob/1.3.40/ChangeLog.md[changelog] for more information about the included changes.

The minimum supported Kotlin Gradle Plugin version is now 1.2.31. Previously it was 1.2.21.

==== Automatic capability conflict resolution

Previous versions of Gradle would automatically select, in case of capability conflicts, the module which has the highest capability version.
Starting from 5.6, this is an opt-in behavior that can be activated using:

```
configurations.all {
   resolutionStrategy.capabilitiesResolution.all { selectHighestVersion() }
}
```

See <<controlling_transitive_dependencies.adoc#sub:capabilities, the capabilities section of the documentation>> for more options.

=== Disabled debug argument parsing in JavaExec

Gradle 5.6 introduced a new DSL element (`JavaForkOptions.debugOptions(Action<JavaDebugOptions>)`) to configure debug properties for forked Java processes. Due to this change, Gradle no longer parses debug-related JVM arguments. Consequently, `JavaForkOptions.getDebu()` no longer returns `true` if the `-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005` or the `-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005` argument is specified to the process.

[[changes_5.5]]
== Upgrading from 5.4 and earlier

=== Deprecations

==== Play

The built-in <<play_plugin.adoc#play_plugin, Play plugin>> has been deprecated and will be replaced by a new link:https://gradle.github.io/playframework[Play Framework plugin] available from the plugin portal.

==== Build Comparison

The _build comparison_ plugin has been deprecated and will be removed in the next major version of Gradle.

link:https://gradle.com/build-scans[Build scans] show much deeper insights into your build and you can use link:https://gradle.com/[Gradle Enterprise] to directly compare two build's build-scans.

=== Potential breaking changes

==== User supplied Eclipse project names may be ignored on conflict

Project names configured via link:{javadocPath}/org/gradle/plugins/ide/eclipse/model/EclipseProject.html[`EclipseProject.setName(...)`] were honored by Gradle and Buildship in all cases, even
when the names caused conflicts and import/synchronization errors.

Gradle can now deduplicate these names if they conflict with other project names in an Eclipse workspace. This may lead to different Eclipse project names for projects with user-specified names.

The upcoming 3.1.1 version of Buildship is required to take advantage of this behavior.

Contributed by link:https://github.com/fraenkelc[Christian Fränkel]

==== Default JaCoCo version upgraded to 0.8.4

<<jacoco_plugin#jacoco_plugin, The JaCoCo plugin>> has been upgraded to use link:http://www.jacoco.org/jacoco/trunk/doc/changes.html[JaCoCo version 0.8.4] instead of 0.8.3 by default.

Contributed by link:https://github.com/Godin[Evgeny Mandrikov]

==== Embedded Ant version upgraded to 1.9.14

The version of Ant distributed with Gradle has been upgraded to link:https://archive.apache.org/dist/ant/RELEASE-NOTES-1.9.14.html[1.9.14] from 1.9.13.

==== `DependencyHandler` now statically exposes `ExtensionAware`

This affects Kotlin DSL build scripts that make use of `ExtensionAware` extension members such as the `extra` properties accessor inside the `dependencies {}` block. The receiver for those members will no longer be the enclosing `Project` instance but the `dependencies` object itself, the innermost `ExtensionAware` conforming receiver. In order to address `Project` extra properties inside `dependencies {}` the receiver must be explicitly qualified i.e. `project.extra` instead of just `extra`. Affected extensions also include `the<T>()` and `configure<T>(T.() -> Unit)`.

==== Improved processing of dependency excludes

Previous versions of Gradle could, in some complex dependency graphs, have a wrong result or a randomized dependency order when lots of excludes were present.
To mitigate this, the algorithm that computes exclusions has been rewritten.
In some rare cases this may cause some differences in resolution, due to the correctness changes.

==== Improved classpath separation for worker processes

The system classpath for worker daemons started by the <<custom_tasks.adoc#worker_api, Worker API>> when using `PROCESS` isolation has been reduced to a minimum set of Gradle infrastructure. User code is still segregated into a separate classloader to isolate it from the Gradle runtime. This should be a transparent change for tasks using the worker API, but previous versions of Gradle mixed user code and Gradle internals in the worker process. Worker actions that rely on things like the `java.class.path` system property may be affected, since `java.class.path` now represents only the classpath of the Gradle internals.

[[changes_5.4]]
== Upgrading from 5.3 and earlier

=== Deprecations

==== Using custom local build cache implementations

Using a custom build cache implementation for the local build cache is now deprecated.
The only allowed type will be `DirectoryBuildCache` going forward.
There is no change in the support for using custom build cache implementations as the remote build cache.

=== Potential breaking changes

==== Use HTTPS when configuring Google Hosted Libraries via `googleApis()`

The Google Hosted Libraries URL accessible via `JavaScriptRepositoriesExtension#GOOGLE_APIS_REPO_URL` was changed to use the HTTPS protocol.
The change also affect the Ivy repository configured via `googleApis()`.

[[changes_5.3]]
== Upgrading from 5.2 and earlier

=== Potential breaking changes

==== Bug fixes in platform resolution

There was a bug from Gradle 5.0 to 5.2.1 (included) where enforced platforms would potentially include dependencies instead of constraints.
This would happen whenever a POM file defined both dependencies and "constraints" (via `<dependencyManagement>`) and that you used `enforcedPlatform`.
Gradle 5.3 fixes this bug, meaning that you might have differences in the resolution result if you relied on this broken behavior.
Similarly, Gradle 5.3 will no longer try to download jars for `platform` and `enforcedPlatform` dependencies (as they should only bring in constraints).

==== Automatic target JVM version

If you apply any of the Java plugins, Gradle will now do its best to select dependencies which match the target compatibility of the module being compiled.
What it means, in practice, is that if you have module A built for Java 8, and module B built for Java 8, then there's no change.
However if B is built for Java 9+, then it's not binary compatible anymore, and Gradle would complain with an error message like the following:

```
Unable to find a matching variant of project :producer:
  - Variant 'apiElements' capability test:producer:unspecified:
      - Required org.gradle.dependency.bundling 'external' and found compatible value 'external'.
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found compatible value 'java-api-jars'.
  - Variant 'runtimeElements' capability test:producer:unspecified:
      - Required org.gradle.dependency.bundling 'external' and found compatible value 'external'.
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found compatible value 'java-runtime-jars'.
```

In general, this is a sign that your project is misconfigured and that your dependencies are not compatible.
However, there are cases where you still may want to do this, for example when only a _subset_ of classes of your module actually need the Java 9 dependencies, and are not intended to be used on earlier releases.
Java in general doesn't encourage you to do this (you should split your module instead), but if you face this problem, you can workaround by disabling this new behavior on the consumer side:

```
java {
   disableAutoTargetJvm()
}
```

==== Bug fix in Maven / Ivy interoperability with dependency substitution

If you have a Maven dependency pointing to an Ivy dependency where the `default` configuration dependencies do not match the `compile` + `runtime` + `master` ones
_and_ that Ivy dependency was substituted (using a `resolutionStrategy.force`, `resolutionStrategy.eachDependency` or `resolutionStrategy.dependencySubstitution`)
then this fix will impact you.
The legacy behaviour of Gradle, prior to 5.0, was still in place instead of being replaced by the changes introduced by improved pom support.

==== Delete operations correctly handle symbolic links on Windows

Gradle no longer ignores the `followSymlink` option on Windows for the `clean` task, all `Delete` tasks, and `project.delete {}` operations in the presence of junction points and symbolic links.

==== Fix in publication of additional artifacts

In previous Gradle versions, additional artifacts registered at the project level were not published by `maven-publish` or `ivy-publish` unless they were also added as artifacts in the publication configuration.

With Gradle 5.3, these artifacts are now properly accounted for and published.

This means that artifacts that are registered both on the project _and_ the publication, Ivy or Maven, will cause publication to fail since it will create duplicate entries.
The fix is to remove these artifacts from the publication configuration.

[[changes_5.2]]
== Upgrading from 5.1 and earlier

=== Potential breaking changes

none

[[changes_5.1]]
== Upgrading from 5.0 and earlier

=== Deprecations

Follow the API links to learn how to deal with these deprecations (if no extra information is provided here):

 * Setters for `classes` and `classpath` on link:{javadocPath}/org/gradle/plugin/devel/tasks/ValidateTaskProperties.html[`ValidateTaskProperties`]

 * There should not be setters for lazy properties like link:{javadocPath}/org/gradle/api/file/ConfigurableFileCollection.html[`ConfigurableFileCollection`].  Use `setFrom` instead. For example,
----
    validateTaskProperties.getClasses().setFrom(fileCollection)
    validateTaskProperties.getClasspath().setFrom(fileCollection)
----

=== Potential breaking changes

The following changes were not previously deprecated:

==== Signing API changes
Input and output files of `Sign` tasks are now tracked via `Signature.getToSign()` and `Signature.getFile()`, respectively.

==== Collection properties default to empty collection

In Gradle 5.0, the collection property instances created using `ObjectFactory` would have no value defined, requiring plugin authors to explicitly set an initial value. This proved to be awkward and error prone so `ObjectFactory` now returns instances with an empty collection as their initial value.

==== Worker API: working directory of a worker can no longer be set

Since JDK 11 no longer supports changing the working directory of a running process, setting the working directory of a worker via its fork options is now prohibited.
All workers now use the same working directory to enable reuse.
Please pass files and directories as arguments instead. See examples in the <<custom_tasks.adoc#worker_api, Worker API documentation>>.

==== Changes to native linking tasks

To expand our idiomatic <<lazy_configuration.adoc#, Provider API>> practices, the install name property from `org.gradle.nativeplatform.tasks.LinkSharedLibrary` is affected by this change.

- `getInstallName()` was changed to return a `Property`.
- `setInstallName(String)` was removed. Use `Property.set()` instead.

==== Passing arguments to Windows Resource Compiler

To expand our idiomatic <<lazy_configuration.adoc#, Provider API>> practices, the `WindowsResourceCompile` task has been converted to use the Provider API.

Passing additional compiler arguments now follow the same pattern as the `CppCompile` and other tasks.

==== Copied configuration no longer shares a list of `beforeResolve` actions with original

The list of `beforeResolve` actions are no longer shared between a copied configuration and the original.
Instead, a copied configuration receives a copy of the `beforeResolve` actions at the time the copy is made.
Any `beforeResolve` actions added after copying (to either configuration) will not be shared between the original and the copy.
This may break plugins that relied on the previous behaviour.

==== Changes to incubating POM customization types

- The type of `MavenPomDeveloper.properties` has changed from `Property<Map<String, String>>` to `MapProperty<String, String>`.
- The type of `MavenPomContributor.properties` has changed from `Property<Map<String, String>>` to `MapProperty<String, String>`.

==== Changes to specifying operating system for native projects

The incubating `operatingSystems` property on native components has been replaced with the link:{javadocPath}/org/gradle/language/cpp/CppComponent.html#getTargetMachines()[targetMachines] property.

==== Changes for archive tasks (`Zip`, `Jar`, `War`, `Ear`, `Tar`)

===== Change in behavior for tasks extending `AbstractArchiveTask`

The `AbstractArchiveTask` has several new properties using the <<lazy_configuration.adoc#sec:lazy_configuration_reference,Provider API>>.
Plugins that extend these types and override methods from the base class may no longer behave the same way.
Internally, `AbstractArchiveTask` prefers the new properties and methods like `getArchiveName()` are façades over the new properties.

If your plugin/build only uses these types (and does not extend them), nothing has changed.

===== Archive tasks fail on duplicate files

Until now archive tasks defaulted to the `INCLUDE` duplicates strategy, allowing the same path to exist multiple times in an archive.

In Gradle 6.0 we are switching to `FAIL`, prohibiting duplicate files in archives.
If you still want to allow them, you can be specify that explicitly:

```
task archive(type: Zip) {
    duplicatesStrategy = DuplicatesStrategy.INCLUDE // allow duplicates
    archiveName = 'archive.zip'
    from 'src'
}
```

*Note* that `Copy` and `Sync` tasks are unaffected: they still use the `INCLUDE` duplicates strategy as default.

////
== Changes in detail

[[rel5.X:title]]
=== [5.X] Title

Details...
////

// 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_5]]
= Upgrading your build from Gradle 5.x to 6.0

This chapter provides the information you need to migrate your Gradle 5.x builds to Gradle 6.0. For migrating from Gradle 4.x, complete the <<upgrading_version_4.adoc#upgrading_version_4, 4.x to 5.0 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_6.0]]
== Upgrading from 5.6 and earlier

=== Deprecations

==== Dependencies should no longer be declared using the compile and runtime configurations

The usage of the `compile` and `runtime` configurations in the Java ecosystem plugins has been discouraged for some time now.
These configurations, and their counterparts in other sources sets (e.g. `testCompile` and `testRuntime`), should not be utilised anymore.
Instead, use the `implementation`, `api`, `compileOnly` and `runtimeOnly` configurations to declare dependencies and the `compileClasspath` and `runtimeClasspath` configurations to resolve dependencies.

==== Local build cache type shouldn't be specified

When configuring the local build cache the use of `BuildCacheConfiguration.local(Class)` and `local(Class, Action)` has now been deprecated; use `getLocal()` or `local(Action)` instead.
These methods now assume the local build cache type to be `DirectoryBuildCache`.

=== Potential breaking changes

==== Local build cache is always a directory cache

In the past it was possible to use any build cache implementation as the `local` cache.
This is not allowed anymore as the local cache is always a `DirectoryBuildCache`.
Calls to `BuildCacheConfiguration.local(Class)` with anything other than `DirectoryBuildCache` as the type will fail the build.
Use `getLocal()` and `local(Action)` instead.
These methods now assume the local build cache type to be `DirectoryBuildCache`.

==== Failing to pack or unpack cached results will now fail the build

In the past when Gradle encountered a problem while packaging the results of a cached task, it would ignore the problem and try to continue running the build.
Similarly, having encountered a corrupt cached artifact during unpacking Gradle would try to remove whatever was already unpacked of the output and re-execute the task to make sure the build had a chance to succeed.

While this behavior could be helpful to maintain executing build no matter what, hiding the problems this way can lead to reduced cache performance.
In Gradle 6.0 we are switching to failing fast, and both pack and unpack errors will result the build to fail.
Doing so allows these problems to be surfaced more easily.

==== Gradle Module Metadata is always published

[Gradle Module Metadata](https://blog.gradle.org/gradle-metadata-1.0), officially introduced in Gradle 5.3, was created to solve many of the problems that have plagued dependency management for years, in particular, but not exclusively, in the Java ecosystem.
With Gradle 6.0, Gradle Module Metadata is enabled by default.
This means, if you are publishing libraries with Gradle, using the <<publishing_maven.adoc#,maven-publish>> or <<publishing_ivy.adoc#,ivy-publish>> plugin, the Gradle Module Metadata file is always published *in addition* to the traditional metadata.
The traditional metadata file will contain a marker so that Gradle knows that there is additional metadata to consume.

==== Maven or Ivy repositories are no longer queried for artifacts without metadata by default

If Gradle fails to locate the metadata file (`.pom` or `ivy.xml`) of a module in a repository defined in the `repositories { }` section, it now assumes that the module does not exist in that repository.
Previously, Gradle was also looking for a default artifact (`.jar`) which usually also does not exist.
This often caused large number of unnecessary requests when using multiple repositories.
This change speeds up builds with many dependencies using multiple repositories.
You can opt into the previous behavior for selected repositories by adding the `artifact()` <<declaring_repositories.adoc#sec:repository-content-filtering,repository content filter>>.

==== `@Nullable` annotation is gone

The `org.gradle.api.Nullable` annotation type has been removed. Use `javax.annotation.Nullable` from JSR-305 instead.

==== Task validation changes

- `ValidateTaskProperties.setClasses()` is now removed. Use `getClasses().setFrom()` instead.
- `ValidateTaskProperties.setClasspath()` is now removed. use `getClasspath().setFrom()` instead.

==== The FindBugs plugin has been removed

The deprecated FindBugs plugin has been removed.
As an alternative, you can use the link:https://plugins.gradle.org/plugin/com.github.spotbugs[SpotBugs plugin] from the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The JDepend plugin has been removed

The deprecated JDepend plugin has been removed.
There are a number of community-provided plugins for code and architecture analysis available on the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The OSGI plugin has been removed

The deprecated OSGI plugin has been removed.  There are a number of community-provided OSGI plugins available on the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The announce and build-announcements plugins have been removed

The deprecated announce and build-announcements plugins have been removed.  There are a number of community-provided plugins for sending out notifications available on the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The Compare Gradle Builds plugin has been removed

The deprecated Compare Gradle Builds plugin has been removed.
Please use https://scans.gradle.com/[build scans] for build analysis and comparison.

==== Changes to the task container

The following deprecated methods on the task container now result in errors:

- `TaskContainer.add()`
- `TaskContainer.addAll()`
- `TaskContainer.remove()`
- `TaskContainer.removeAll()`
- `TaskContainer.retainAll()`
- `TaskContainer.clear()`
- `TaskContainer.iterator().remove()`

Additionally, the following deprecated functionality now results in an error:

- Replacing a task that has already been realized.
- Replacing a registered (unrealized) task with an incompatible type. A compatible type is the same type or a sub-type of the registered type.
- Replacing a task that has never been registered.

==== Updates to bundled Gradle dependencies

- Groovy has been updated to http://groovy-lang.org/changelogs/changelog-2.5.8.html[Groovy 2.5.8].
- Kotlin has been updated to https://blog.jetbrains.com/kotlin/2019/08/kotlin-1-3-50-released/[Kotlin 1.3.50].

The following breaking changes will appear as deprecation warnings with Gradle 5.6:

Miscellaneous::

* The `org.gradle.util.GUtil.savePropertiesNoDateComment` has been removed. There is no public replacement for this internal method.
* The deprecated class `org.gradle.api.tasks.compile.CompilerArgumentProvider` has been removed.
  Use link:{javadocPath}/org/gradle/process/CommandLineArgumentProvider.html[org.gradle.process.CommandLineArgumentProvider] instead.
* The deprecated class `org.gradle.api.ConventionProperty` has been removed.
  Use link:{javadocPath}/org/gradle/api/provider/Provider.html[Providers] instead of convention properties.
* The deprecated class `org.gradle.reporting.DurationFormatter` has been removed.
* The bridge method `org.gradle.api.tasks.TaskInputs.property(String name, @Nullable Object value)` returning `TaskInputs` has been removed.
  A plugin using the method must be compiled with Gradle 4.3 to work on Gradle 6.0.
* The following setters have been removed from `JacocoReportBase`:
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:executionData[executionData] - use `getExecutionData().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:sourceDirectories[sourceDirectories] - use `getSourceDirectories().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:classDirectories[classDirectories] - use `getClassDirectories().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:additionalClassDirs[additionalClassDirs] - use `getAdditionalClassDirs().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:additionalSourceDirs[additionalSourceDirs] - use `getAdditionalSourceDirs().setFrom()` instead.
* The `append` property on `JacocoTaskExtension` has been removed.
  `append` is now always configured to be true for the Jacoco agent.
* The `configureDefaultOutputPathForJacocoMerge` method on `JacocoPlugin` has been removed.
  The method was never meant to be public.
* File paths in link:{javadocPath}/org/gradle/plugins/ear/descriptor/DeploymentDescriptor.html#getFileName--[deployment descriptor file name] for the ear plugin are not allowed any more.
  Use a simple name, like `application.xml`, instead.
* The `org.gradle.testfixtures.ProjectBuilder` constructor has been removed. Please use `ProjectBuilder.builder()` instead.
* When <<groovy_plugin.adoc#sec:incremental_groovy_compilation,incremental Groovy compilation>> is enabled, a wrong configuration of the source roots or enabling Java annotation for Groovy now fails the build.
  Disable incremental Groovy compilation when you want to compile in those cases.
* `ComponentSelectionRule` no longer can inject the metadata or ivy descriptor.
  Use the methods on the <<declaring_dependency_versions.adoc#sec:component_selection_rules,`ComponentSelection` parameter>> instead.
* Declaring an <<custom_tasks.adoc#incremental_tasks,incremental task>> without declaring outputs is now an error.
  Declare file outputs or use link:{javadocPath}/org/gradle/api/tasks/TaskOutputs.html#upToDateWhen-groovy.lang.Closure-[TaskOutputs.upToDateWhen()] instead.

[[changes_5.6]]
== Upgrading from 5.5 and earlier

=== Deprecations

==== BuildSrc usage in Gradle settings

Access to the buildSrc project and its dependencies in gradle settings scripts is now deprecated.
This is due to plans to make initialization of gradle builds more efficient.

This will become an error in Gradle 6.0.

==== Changing the contents of `ConfigurableFileCollection` task properties after task starts execution

When a task property has type `ConfigurableFileCollection`, then the file collection referenced by the property will ignore changes made to the contents of the collection once the task
starts execution. This has two benefits. Firstly, this prevents accidental changes to the property value during task execution which can cause Gradle up-to-date checks and build cache lookup
using different values to those used by the task action. Secondly, this improves performance as Gradle can calculate the value once and cache the result.

This will become an error in Gradle 6.0.

==== Creating `SignOperation` instances

Creating `SignOperation` instances directly is now deprecated. Instead, the methods of `SigningExtension` should be used to create these instances.

This will become an error in Gradle 6.0.

==== Declaring an incremental task without outputs

Declaring an <<custom_tasks.adoc#incremental_tasks,incremental task>> without declaring outputs is now deprecated.
Declare file outputs or use link:{javadocPath}/org/gradle/api/tasks/TaskOutputs.html#upToDateWhen-groovy.lang.Closure-[TaskOutputs.upToDateWhen()] instead.

This will become an error in Gradle 6.0.

==== `WorkerExecutor.submit()` is deprecated

The `WorkerExecutor.submit()` method is now deprecated.
The new `noIsolation()`, `classLoaderIsolation()` and `processIsolation()` methods should now be used to submit work.
See <<custom_tasks.adoc#using-the-worker-api, the userguide>> for more information on using these methods.

`WorkerExecutor.submit()` will be removed in Gradle 7.0.

=== Potential breaking changes

==== Task dependencies are honored for task `@Input` properties whose value is a `Property`

Previously, task dependencies would be ignored for task `@Input` properties of type `Property<T>`. These are now honored, so that it is possible to attach a task output property to a task `@Input` property.

This may introduce unexpected cycles in the task dependency graph, where the value of an output property is mapped to produce a value for an input property.

==== Declaring task dependencies using a file `Provider` that does not represent a task output

Previously, it was possible to pass `Task.dependsOn()` a `Provider<File>`, `Provider<RegularFile>` or `Provider<Directory>` instance that did not represent a task output. These providers would be silently ignored.

This is now an error because Gradle does not know how to build files that are not task outputs.

*Note* that it is still possible to to pass `Task.dependsOn()` a `Provider` that returns a file and that represents a task output, for example `myTask.dependsOn(jar.archiveFile)` or `myTask.dependsOn(taskProvider.flatMap { it.outputDirectory })`, when the `Provider` is an annotated `@OutputFile` or `@OutputDirectory` property of a task.

==== Setting `Property` value to `null` uses the property convention

Previously, calling `Property.set(null)` would always reset the value of the property to 'not defined'. Now, the convention that is associated with the property using the `convention()` method
will be used to determine the value of the property.

==== Enhanced validation of names for `publishing.publications` and `publishing.repositories`

The repository and publication names are used to construct task names for publishing. It was possible to supply a name that would result in an invalid task name. Names for publications and repositories are now restricted to `[A-Za-z0-9_\\-.]+`.

==== Restricted Worker API classloader and process classpath

Gradle now prevents internal dependencies (like Guava) from leaking into the classpath used by Worker API actions. This fixes link:https://github.com/gradle/gradle/issues/3698[an issue] where a worker needs to use a dependency that is also used by Gradle internally.

In previous releases, it was possible to rely on these leaked classes. Plugins relying on this behavior will now fail.  To fix the plugin, the worker should explicitly include all required dependencies in its classpath.

==== Default PMD version upgraded to 6.15.0

<<pmd_plugin#pmd_plugin, The PMD plugin>> has been upgraded to use link:https://pmd.github.io/pmd-6.15.0/pmd_release_notes.html[PMD version 6.15.0] instead of 6.8.0 by default.

Contributed by link:https://github.com/wreulicke[wreulicke]

==== Configuration copies have unique names

Previously, all copies of a configuration always had the name `<OriginConfigurationName>Copy`. Now when creating multiple copies, each will have a unique name by adding an index starting from the second copy. (e.g. `CompileOnlyCopy2`)

==== Changed classpath filtering for Eclipse

Gradle 5.6 no longer supplies custom classpath attributes in the Eclipse model. Instead, it provides the attributes for link:https://www.eclipse.org/eclipse/news/4.8/jdt.php#jdt-test-sources[Eclipse test sources]. This change requires Buildship version 3.1.1 or later.

==== Embedded Kotlin upgraded to 1.3.41

Gradle Kotlin DSL scripts and Gradle Plugins authored using the `kotlin-dsl` plugin are now compiled using Kotlin 1.3.41.

Please see the Kotlin link:https://blog.jetbrains.com/kotlin/2019/06/kotlin-1-3-40-released/[blog post] and link:https://github.com/JetBrains/kotlin/blob/1.3.40/ChangeLog.md[changelog] for more information about the included changes.

The minimum supported Kotlin Gradle Plugin version is now 1.2.31. Previously it was 1.2.21.

==== Automatic capability conflict resolution

Previous versions of Gradle would automatically select, in case of capability conflicts, the module which has the highest capability version.
Starting from 5.6, this is an opt-in behavior that can be activated using:

```
configurations.all {
   resolutionStrategy.capabilitiesResolution.all { selectHighestVersion() }
}
```

See <<controlling_transitive_dependencies.adoc#sub:capabilities, the capabilities section of the documentation>> for more options.

=== Disabled debug argument parsing in JavaExec

Gradle 5.6 introduced a new DSL element (`JavaForkOptions.debugOptions(Action<JavaDebugOptions>)`) to configure debug properties for forked Java processes. Due to this change, Gradle no longer parses debug-related JVM arguments. Consequently, `JavaForkOptions.getDebu()` no longer returns `true` if the `-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005` or the `-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005` argument is specified to the process.

[[changes_5.5]]
== Upgrading from 5.4 and earlier

=== Deprecations

==== Play

The built-in <<play_plugin.adoc#play_plugin, Play plugin>> has been deprecated and will be replaced by a new link:https://gradle.github.io/playframework[Play Framework plugin] available from the plugin portal.

==== Build Comparison

The _build comparison_ plugin has been deprecated and will be removed in the next major version of Gradle.

link:https://gradle.com/build-scans[Build scans] show much deeper insights into your build and you can use link:https://gradle.com/[Gradle Enterprise] to directly compare two build's build-scans.

=== Potential breaking changes

==== User supplied Eclipse project names may be ignored on conflict

Project names configured via link:{javadocPath}/org/gradle/plugins/ide/eclipse/model/EclipseProject.html[`EclipseProject.setName(...)`] were honored by Gradle and Buildship in all cases, even
when the names caused conflicts and import/synchronization errors.

Gradle can now deduplicate these names if they conflict with other project names in an Eclipse workspace. This may lead to different Eclipse project names for projects with user-specified names.

The upcoming 3.1.1 version of Buildship is required to take advantage of this behavior.

Contributed by link:https://github.com/fraenkelc[Christian Fränkel]

==== Default JaCoCo version upgraded to 0.8.4

<<jacoco_plugin#jacoco_plugin, The JaCoCo plugin>> has been upgraded to use link:http://www.jacoco.org/jacoco/trunk/doc/changes.html[JaCoCo version 0.8.4] instead of 0.8.3 by default.

Contributed by link:https://github.com/Godin[Evgeny Mandrikov]

==== Embedded Ant version upgraded to 1.9.14

The version of Ant distributed with Gradle has been upgraded to link:https://archive.apache.org/dist/ant/RELEASE-NOTES-1.9.14.html[1.9.14] from 1.9.13.

==== `DependencyHandler` now statically exposes `ExtensionAware`

This affects Kotlin DSL build scripts that make use of `ExtensionAware` extension members such as the `extra` properties accessor inside the `dependencies {}` block. The receiver for those members will no longer be the enclosing `Project` instance but the `dependencies` object itself, the innermost `ExtensionAware` conforming receiver. In order to address `Project` extra properties inside `dependencies {}` the receiver must be explicitly qualified i.e. `project.extra` instead of just `extra`. Affected extensions also include `the<T>()` and `configure<T>(T.() -> Unit)`.

==== Improved processing of dependency excludes

Previous versions of Gradle could, in some complex dependency graphs, have a wrong result or a randomized dependency order when lots of excludes were present.
To mitigate this, the algorithm that computes exclusions has been rewritten.
In some rare cases this may cause some differences in resolution, due to the correctness changes.

==== Improved classpath separation for worker processes

The system classpath for worker daemons started by the <<custom_tasks.adoc#worker_api, Worker API>> when using `PROCESS` isolation has been reduced to a minimum set of Gradle infrastructure. User code is still segregated into a separate classloader to isolate it from the Gradle runtime. This should be a transparent change for tasks using the worker API, but previous versions of Gradle mixed user code and Gradle internals in the worker process. Worker actions that rely on things like the `java.class.path` system property may be affected, since `java.class.path` now represents only the classpath of the Gradle internals.

[[changes_5.4]]
== Upgrading from 5.3 and earlier

=== Deprecations

==== Using custom local build cache implementations

Using a custom build cache implementation for the local build cache is now deprecated.
The only allowed type will be `DirectoryBuildCache` going forward.
There is no change in the support for using custom build cache implementations as the remote build cache.

=== Potential breaking changes

==== Use HTTPS when configuring Google Hosted Libraries via `googleApis()`

The Google Hosted Libraries URL accessible via `JavaScriptRepositoriesExtension#GOOGLE_APIS_REPO_URL` was changed to use the HTTPS protocol.
The change also affect the Ivy repository configured via `googleApis()`.

[[changes_5.3]]
== Upgrading from 5.2 and earlier

=== Potential breaking changes

==== Bug fixes in platform resolution

There was a bug from Gradle 5.0 to 5.2.1 (included) where enforced platforms would potentially include dependencies instead of constraints.
This would happen whenever a POM file defined both dependencies and "constraints" (via `<dependencyManagement>`) and that you used `enforcedPlatform`.
Gradle 5.3 fixes this bug, meaning that you might have differences in the resolution result if you relied on this broken behavior.
Similarly, Gradle 5.3 will no longer try to download jars for `platform` and `enforcedPlatform` dependencies (as they should only bring in constraints).

==== Automatic target JVM version

If you apply any of the Java plugins, Gradle will now do its best to select dependencies which match the target compatibility of the module being compiled.
What it means, in practice, is that if you have module A built for Java 8, and module B built for Java 8, then there's no change.
However if B is built for Java 9+, then it's not binary compatible anymore, and Gradle would complain with an error message like the following:

```
Unable to find a matching variant of project :producer:
  - Variant 'apiElements' capability test:producer:unspecified:
      - Required org.gradle.dependency.bundling 'external' and found compatible value 'external'.
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found compatible value 'java-api-jars'.
  - Variant 'runtimeElements' capability test:producer:unspecified:
      - Required org.gradle.dependency.bundling 'external' and found compatible value 'external'.
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found compatible value 'java-runtime-jars'.
```

In general, this is a sign that your project is misconfigured and that your dependencies are not compatible.
However, there are cases where you still may want to do this, for example when only a _subset_ of classes of your module actually need the Java 9 dependencies, and are not intended to be used on earlier releases.
Java in general doesn't encourage you to do this (you should split your module instead), but if you face this problem, you can workaround by disabling this new behavior on the consumer side:

```
java {
   disableAutoTargetJvm()
}
```

==== Bug fix in Maven / Ivy interoperability with dependency substitution

If you have a Maven dependency pointing to an Ivy dependency where the `default` configuration dependencies do not match the `compile` + `runtime` + `master` ones
_and_ that Ivy dependency was substituted (using a `resolutionStrategy.force`, `resolutionStrategy.eachDependency` or `resolutionStrategy.dependencySubstitution`)
then this fix will impact you.
The legacy behaviour of Gradle, prior to 5.0, was still in place instead of being replaced by the changes introduced by improved pom support.

==== Delete operations correctly handle symbolic links on Windows

Gradle no longer ignores the `followSymlink` option on Windows for the `clean` task, all `Delete` tasks, and `project.delete {}` operations in the presence of junction points and symbolic links.

==== Fix in publication of additional artifacts

In previous Gradle versions, additional artifacts registered at the project level were not published by `maven-publish` or `ivy-publish` unless they were also added as artifacts in the publication configuration.

With Gradle 5.3, these artifacts are now properly accounted for and published.

This means that artifacts that are registered both on the project _and_ the publication, Ivy or Maven, will cause publication to fail since it will create duplicate entries.
The fix is to remove these artifacts from the publication configuration.

[[changes_5.2]]
== Upgrading from 5.1 and earlier

=== Potential breaking changes

none

[[changes_5.1]]
== Upgrading from 5.0 and earlier

=== Deprecations

Follow the API links to learn how to deal with these deprecations (if no extra information is provided here):

 * Setters for `classes` and `classpath` on link:{javadocPath}/org/gradle/plugin/devel/tasks/ValidateTaskProperties.html[`ValidateTaskProperties`]

 * There should not be setters for lazy properties like link:{javadocPath}/org/gradle/api/file/ConfigurableFileCollection.html[`ConfigurableFileCollection`].  Use `setFrom` instead. For example,
----
    validateTaskProperties.getClasses().setFrom(fileCollection)
    validateTaskProperties.getClasspath().setFrom(fileCollection)
----

=== Potential breaking changes

The following changes were not previously deprecated:

==== Signing API changes
Input and output files of `Sign` tasks are now tracked via `Signature.getToSign()` and `Signature.getFile()`, respectively.

==== Collection properties default to empty collection

In Gradle 5.0, the collection property instances created using `ObjectFactory` would have no value defined, requiring plugin authors to explicitly set an initial value. This proved to be awkward and error prone so `ObjectFactory` now returns instances with an empty collection as their initial value.

==== Worker API: working directory of a worker can no longer be set

Since JDK 11 no longer supports changing the working directory of a running process, setting the working directory of a worker via its fork options is now prohibited.
All workers now use the same working directory to enable reuse.
Please pass files and directories as arguments instead. See examples in the <<custom_tasks.adoc#worker_api, Worker API documentation>>.

==== Changes to native linking tasks

To expand our idiomatic <<lazy_configuration.adoc#, Provider API>> practices, the install name property from `org.gradle.nativeplatform.tasks.LinkSharedLibrary` is affected by this change.

- `getInstallName()` was changed to return a `Property`.
- `setInstallName(String)` was removed. Use `Property.set()` instead.

==== Passing arguments to Windows Resource Compiler

To expand our idiomatic <<lazy_configuration.adoc#, Provider API>> practices, the `WindowsResourceCompile` task has been converted to use the Provider API.

Passing additional compiler arguments now follow the same pattern as the `CppCompile` and other tasks.

==== Copied configuration no longer shares a list of `beforeResolve` actions with original

The list of `beforeResolve` actions are no longer shared between a copied configuration and the original.
Instead, a copied configuration receives a copy of the `beforeResolve` actions at the time the copy is made.
Any `beforeResolve` actions added after copying (to either configuration) will not be shared between the original and the copy.
This may break plugins that relied on the previous behaviour.

==== Changes to incubating POM customization types

- The type of `MavenPomDeveloper.properties` has changed from `Property<Map<String, String>>` to `MapProperty<String, String>`.
- The type of `MavenPomContributor.properties` has changed from `Property<Map<String, String>>` to `MapProperty<String, String>`.

==== Changes to specifying operating system for native projects

The incubating `operatingSystems` property on native components has been replaced with the link:{javadocPath}/org/gradle/language/cpp/CppComponent.html#getTargetMachines()[targetMachines] property.

==== Changes for archive tasks (`Zip`, `Jar`, `War`, `Ear`, `Tar`)

===== Change in behavior for tasks extending `AbstractArchiveTask`

The `AbstractArchiveTask` has several new properties using the <<lazy_configuration.adoc#sec:lazy_configuration_reference,Provider API>>.
Plugins that extend these types and override methods from the base class may no longer behave the same way.
Internally, `AbstractArchiveTask` prefers the new properties and methods like `getArchiveName()` are façades over the new properties.

If your plugin/build only uses these types (and does not extend them), nothing has changed.

===== Archive tasks fail on duplicate files

Until now archive tasks defaulted to the `INCLUDE` duplicates strategy, allowing the same path to exist multiple times in an archive.

In Gradle 6.0 we are switching to `FAIL`, prohibiting duplicate files in archives.
If you still want to allow them, you can be specify that explicitly:

```
task archive(type: Zip) {
    duplicatesStrategy = DuplicatesStrategy.INCLUDE // allow duplicates
    archiveName = 'archive.zip'
    from 'src'
}
```

*Note* that `Copy` and `Sync` tasks are unaffected: they still use the `INCLUDE` duplicates strategy as default.

////
== Changes in detail

[[rel5.X:title]]
=== [5.X] Title

Details...
////


Improve single lockfile per project documentation

Issue #12450

[[dependency-locking]]
= Locking dependency versions

Use of dynamic dependency versions (e.g. `1.+` or `[1.0,2.0)`) makes builds non-deterministic.
This causes builds to break without any obvious change, and worse, can be caused by a transitive dependency that the build author has no control over.

To achieve https://reproducible-builds.org/[reproducible builds], it is necessary to _lock_ versions of dependencies and transitive dependencies such that a build with the same inputs will always resolve the same module versions.
This is called _dependency locking_.

It enables, amongst others, the following scenarios:

* Companies dealing with multi repositories no longer need to rely on `-SNAPSHOT` or changing dependencies,
which sometimes result in cascading failures when a dependency introduces a bug or incompatibility.
Now dependencies can be declared against major or minor version range, enabling to test with the latest versions on CI while leveraging locking for stable developer builds.
* Teams that want to always use the latest of their dependencies can use dynamic versions, locking their dependencies only for releases.
The release tag will contain the lock states, allowing that build to be fully reproducible when bug fixes need to be developed.

Combined with <<publishing_maven.adoc#publishing_maven:resolved_dependencies,publishing resolved versions>>, you can also replace the declared dynamic version part at publication time.
Consumers will instead see the versions that your release resolved.

Locking is enabled per <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,dependency configuration>>.
Once enabled, you must create an initial lock state.
It will cause Gradle to verify that resolution results do not change, resulting in the same selected dependencies even if newer versions are produced.
Modifications to your build that would impact the resolved set of dependencies will cause it to fail.
This makes sure that changes, either in published dependencies or build definitions, do not alter resolution without adapting the lock state.

[NOTE]
====
Dependency locking makes sense only with <<dynamic_versions.adoc#sub:declaring_dependency_with_dynamic_version,dynamic versions>>.
It will have no impact on <<dynamic_versions.adoc#sub:declaring_dependency_with_changing_version,changing versions>> (like `-SNAPSHOT`) whose coordinates remain the same, though the content may change.
Gradle will even emit a warning when persisting lock state and changing dependencies are present in the resolution result.
====

== Enabling locking on configurations

Locking of a configuration happens through the link:{groovyDslPath}/org.gradle.api.artifacts.ResolutionStrategy.html[ResolutionStrategy]:

.Locking a specific configuration
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/groovy",files="build.gradle[tags=locking-one]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-one]"]
====

Or the following, as a way to lock all configurations:

.Locking all configurations
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingAllConfigurations/groovy",files="build.gradle[tags=locking-all]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingAllConfigurations/kotlin",files="build.gradle.kts[tags=locking-all]"]
====

[NOTE]
====
Only configurations that can be resolved will have lock state attached to them.
Applying locking on non resolvable-configurations is simply a no-op.
====

[NOTE]
====
The above will lock all _project_ configurations, but not the _buildscript_ ones.
====

You can also disable locking on a specific configuration.
This can be useful if a plugin configured locking on all configurations but you happen to add one that should not be locked.

.Unlocking a specific configuration
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/unlockingSingleConfiguration/groovy",files="build.gradle[tags=locking-one]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/unlockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-one]"]
====

=== Locking buildscript classpath configuration

If you apply plugins to your build, you may want to leverage dependency locking there as well.
In order to lock the <<plugins.adoc#sec:applying_plugins_buildscript,`classpath` configuration>> used for script plugins, do the following:

.Locking buildscript classpath configuration
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingClasspathConfiguration/groovy",files="build.gradle[tags=locking-classpath]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingClasspathConfiguration/kotlin",files="build.gradle.kts[tags=locking-classpath]"]
====

== Generating and updating dependency locks

In order to generate or update lock state, you specify the `--write-locks` command line argument in addition to the normal tasks that would trigger configurations to be resolved.
This will cause the creation of lock state for each resolved configuration in that build execution.
Note that if lock state existed previously, it is overwritten.

[[lock_all_configurations_in_one_build_execution]]
=== Lock all configurations in one build execution

When locking multiple configurations, you may want to lock them all at once, during a single build execution.

For this, you have two options:

* Run `gradle dependencies --write-locks`.
This will effectively lock all resolvable configurations that have locking enabled.
Note that in a multi project setup, `dependencies` only is executed on _one_ project, the root one in this case.
* Declare a custom task that will resolve all configurations

.Resolving all configurations
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingAllConfigurations/groovy",files="build.gradle[tags=resolve-all]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingAllConfigurations/kotlin",files="build.gradle.kts[tags=resolve-all]"]
====

That second option, with proper choosing of configurations, can be the only option in the native world, where not all configurations can be resolved on a single platform.

== Lock state location and format

Lock state will be preserved in a file located in the folder `gradle/dependency-locks` inside the project or subproject directory.
Each file is named by the configuration it locks and has the `lockfile` extension.
The one exception to this rule is for configurations for the <<plugins.adoc#sec:applying_plugins_buildscript,buildscript itself>>.
In that case the configuration name will be prefixed with `buildscript-`.

The content of the file is a module notation per line, with a header giving some context.
Module notations are ordered alphabetically, to ease diffs.

.Lockfile content
[listing]
.gradle/dependency-locks/compileClasspath.lockfile
----
include::{samplesPath}/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/groovy/gradle/dependency-locks/compileClasspath.lockfile[]
----

which matches the following dependency declaration:

.Dynamic dependency declaration
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/groovy",files="build.gradle[tags=locking-deps]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-deps]"]
====

== Running a build with lock state present

The moment a build needs to resolve a configuration that has locking enabled and it finds a matching lock state,
it will use it to verify that the given configuration still resolves the same versions.

A successful build indicates that the same dependencies are used as stored in the lock state, regardless if new versions matching the dynamic selector have been produced.

The complete validation is as follows:

* Existing entries in the lock state must be matched in the build
** A version mismatch or missing resolved module causes a build failure
* Resolution result must not contain extra dependencies compared to the lock state

[[fine_tuning_dependency_locking_behaviour_with_lock_mode]]
=== Fine tuning dependency locking behaviour with lock mode

While the default lock mode behaves as described above, two other modes are available:

Strict mode::
In this mode, in addition to the validations above, dependency locking will fail if a configuration marked as _locked_ does not have lock state associated with it.

Lenient mode::
In this mode, dependency locking will still pin dynamic versions but otherwise changes to the dependency resolution are no longer errors.

The lock mode can be controlled from the `dependencyLocking` block as shown below:

.Setting the lock mode
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockModeSelection/groovy",files="build.gradle[tags=lock-mode]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockModeSelection/kotlin",files="build.gradle.kts[tags=lock-mode]"]
====

[[selectively_updating_lock_state_entries]]
== Selectively updating lock state entries

In order to update only specific modules of a configuration, you can use the `--update-locks` command line flag.
It takes a comma (`,`) separated list of module notations.
In this mode, the existing lock state is still used as input to resolution, filtering out the modules targeted by the update.

----
❯ gradle classes --update-locks org.apache.commons:commons-lang3,org.slf4j:slf4j-api
----

Wildcards, indicated with `*`, can be used in the group or module name. They can be the only character or appear at the end of the group or module respectively.
The following wildcard notation examples are valid:

* `org.apache.commons:*`: will let all modules belonging to group `org.apache.commons` update
* `*:guava`: will let all modules named `guava`, whatever their group, update
* `org.springframework.spring*:spring*`: will let all modules having their group starting with `org.springframework.spring` and name starting with `spring` update

[NOTE]
====
The resolution may cause other module versions to update, as dictated by the Gradle resolution rules.
====

== Disabling dependency locking

. Make sure that the configuration for which you no longer want locking is not configured with locking.
. Remove the file matching the configurations where you no longer want locking.

If you only perform the second step above, then locking will effectively no longer be applied.
However, if that configuration happens to be resolved in the future at a time where lock state is persisted, it will once again be locked.

== Single lock file per project

Gradle supports an improved lock file format.
The goal is to have only a single lock file per project, which contains the lock state for all configurations of said project.
By default, the file is named `gradle.lockfile` and is located inside the project directory.
The lock state for the buildscript itself is found in a file named `buildscript-gradle.lockfile` inside the project directory.

The main benefit is a substantial reduction in the number of lock files compared to the format requiring one lockfile per locked configuration.

This format requires a migration for existing locking users and is thus opt-in.

[NOTE]
====
The objective is to default to this single lock file per project in Gradle 7.0.
====

The format can be activated by enabling the matching <<feature_lifecycle#feature_preview, feature preview>>:

.Single lock file per project activation
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/groovy",files="settings.gradle[]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/kotlin",files="settings.gradle.kts[]"]
====

Then with the following dependency declaration and locked configurations:

.Explicit locking
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/groovy",files="build.gradle[tags=locking-explicit]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/kotlin",files="build.gradle.kts[tags=locking-explicit]"]
====

The lockfile will have the following content:

[listing]
.gradle.lockfile
----
include::{samplesPath}/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/groovy/gradle.lockfile[]
----

* Each line still represents a single dependency in the `group:artifact:version` notation
* It then lists all configurations that contain the given dependency
* The last line of the file lists all empty configurations, that is configurations known to have no dependencies

=== Migrating to the single lockfile per project format

Once you have activated the feature preview (see above), you can simply follow the documentation for <<#lock_all_configurations_in_one_build_execution, writing>> or <<#selectively_updating_lock_state_entries, updating>> dependency lock state.

Then after confirming the single lock file per project contains the lock state for a given configuration, the matching per configuration lock file can be removed from `gradle/dependency-locks`.

=== Configuring the per project lock file name and location

When using the single lock file per project, you can configure its name and location.
The main reason for providing this is to enable having a file name that is determined by some project properties, effectively allowing a single project to store different lock state for different execution contexts.
One trivial example in the JVM ecosystem is the Scala version that is often found in artifact coordinates.

.Changing the lock file name
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/groovy",files="build.gradle[tags=locking-file-name]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/kotlin",files="build.gradle.kts[tags=locking-file-name]"]
====

[[locking_limitations]]
== Locking limitations

* Locking cannot yet be applied to source dependencies.

== Nebula locking plugin

This feature is inspired by the https://github.com/nebula-plugins/gradle-dependency-lock-plugin[Nebula Gradle dependency lock plugin].

[[dependency-locking]]
= Locking dependency versions

Use of dynamic dependency versions (e.g. `1.+` or `[1.0,2.0)`) makes builds non-deterministic.
This causes builds to break without any obvious change, and worse, can be caused by a transitive dependency that the build author has no control over.

To achieve https://reproducible-builds.org/[reproducible builds], it is necessary to _lock_ versions of dependencies and transitive dependencies such that a build with the same inputs will always resolve the same module versions.
This is called _dependency locking_.

It enables, amongst others, the following scenarios:

* Companies dealing with multi repositories no longer need to rely on `-SNAPSHOT` or changing dependencies,
which sometimes result in cascading failures when a dependency introduces a bug or incompatibility.
Now dependencies can be declared against major or minor version range, enabling to test with the latest versions on CI while leveraging locking for stable developer builds.
* Teams that want to always use the latest of their dependencies can use dynamic versions, locking their dependencies only for releases.
The release tag will contain the lock states, allowing that build to be fully reproducible when bug fixes need to be developed.

Combined with <<publishing_maven.adoc#publishing_maven:resolved_dependencies,publishing resolved versions>>, you can also replace the declared dynamic version part at publication time.
Consumers will instead see the versions that your release resolved.

Locking is enabled per <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,dependency configuration>>.
Once enabled, you must create an initial lock state.
It will cause Gradle to verify that resolution results do not change, resulting in the same selected dependencies even if newer versions are produced.
Modifications to your build that would impact the resolved set of dependencies will cause it to fail.
This makes sure that changes, either in published dependencies or build definitions, do not alter resolution without adapting the lock state.

[NOTE]
====
Dependency locking makes sense only with <<dynamic_versions.adoc#sub:declaring_dependency_with_dynamic_version,dynamic versions>>.
It will have no impact on <<dynamic_versions.adoc#sub:declaring_dependency_with_changing_version,changing versions>> (like `-SNAPSHOT`) whose coordinates remain the same, though the content may change.
Gradle will even emit a warning when persisting lock state and changing dependencies are present in the resolution result.
====

== Enabling locking on configurations

Locking of a configuration happens through the link:{groovyDslPath}/org.gradle.api.artifacts.ResolutionStrategy.html[ResolutionStrategy]:

.Locking a specific configuration
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/groovy",files="build.gradle[tags=locking-one]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-one]"]
====

Or the following, as a way to lock all configurations:

.Locking all configurations
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingAllConfigurations/groovy",files="build.gradle[tags=locking-all]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingAllConfigurations/kotlin",files="build.gradle.kts[tags=locking-all]"]
====

[NOTE]
====
Only configurations that can be resolved will have lock state attached to them.
Applying locking on non resolvable-configurations is simply a no-op.
====

[NOTE]
====
The above will lock all _project_ configurations, but not the _buildscript_ ones.
====

You can also disable locking on a specific configuration.
This can be useful if a plugin configured locking on all configurations but you happen to add one that should not be locked.

.Unlocking a specific configuration
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/unlockingSingleConfiguration/groovy",files="build.gradle[tags=locking-one]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/unlockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-one]"]
====

=== Locking buildscript classpath configuration

If you apply plugins to your build, you may want to leverage dependency locking there as well.
In order to lock the <<plugins.adoc#sec:applying_plugins_buildscript,`classpath` configuration>> used for script plugins, do the following:

.Locking buildscript classpath configuration
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingClasspathConfiguration/groovy",files="build.gradle[tags=locking-classpath]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingClasspathConfiguration/kotlin",files="build.gradle.kts[tags=locking-classpath]"]
====

== Generating and updating dependency locks

In order to generate or update lock state, you specify the `--write-locks` command line argument in addition to the normal tasks that would trigger configurations to be resolved.
This will cause the creation of lock state for each resolved configuration in that build execution.
Note that if lock state existed previously, it is overwritten.

[[lock_all_configurations_in_one_build_execution]]
=== Lock all configurations in one build execution

When locking multiple configurations, you may want to lock them all at once, during a single build execution.

For this, you have two options:

* Run `gradle dependencies --write-locks`.
This will effectively lock all resolvable configurations that have locking enabled.
Note that in a multi project setup, `dependencies` only is executed on _one_ project, the root one in this case.
* Declare a custom task that will resolve all configurations

.Resolving all configurations
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingAllConfigurations/groovy",files="build.gradle[tags=resolve-all]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingAllConfigurations/kotlin",files="build.gradle.kts[tags=resolve-all]"]
====

That second option, with proper choosing of configurations, can be the only option in the native world, where not all configurations can be resolved on a single platform.

== Lock state location and format

Lock state will be preserved in a file located in the folder `gradle/dependency-locks` inside the project or subproject directory.
Each file is named by the configuration it locks and has the `lockfile` extension.
The one exception to this rule is for configurations for the <<plugins.adoc#sec:applying_plugins_buildscript,buildscript itself>>.
In that case the configuration name will be prefixed with `buildscript-`.

The content of the file is a module notation per line, with a header giving some context.
Module notations are ordered alphabetically, to ease diffs.

.Lockfile content
[listing]
.gradle/dependency-locks/compileClasspath.lockfile
----
include::{samplesPath}/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/groovy/gradle/dependency-locks/compileClasspath.lockfile[]
----

which matches the following dependency declaration:

.Dynamic dependency declaration
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/groovy",files="build.gradle[tags=locking-deps]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleConfiguration/kotlin",files="build.gradle.kts[tags=locking-deps]"]
====

== Running a build with lock state present

The moment a build needs to resolve a configuration that has locking enabled and it finds a matching lock state,
it will use it to verify that the given configuration still resolves the same versions.

A successful build indicates that the same dependencies are used as stored in the lock state, regardless if new versions matching the dynamic selector have been produced.

The complete validation is as follows:

* Existing entries in the lock state must be matched in the build
** A version mismatch or missing resolved module causes a build failure
* Resolution result must not contain extra dependencies compared to the lock state

[[fine_tuning_dependency_locking_behaviour_with_lock_mode]]
=== Fine tuning dependency locking behaviour with lock mode

While the default lock mode behaves as described above, two other modes are available:

Strict mode::
In this mode, in addition to the validations above, dependency locking will fail if a configuration marked as _locked_ does not have lock state associated with it.

Lenient mode::
In this mode, dependency locking will still pin dynamic versions but otherwise changes to the dependency resolution are no longer errors.

The lock mode can be controlled from the `dependencyLocking` block as shown below:

.Setting the lock mode
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockModeSelection/groovy",files="build.gradle[tags=lock-mode]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockModeSelection/kotlin",files="build.gradle.kts[tags=lock-mode]"]
====

[[selectively_updating_lock_state_entries]]
== Selectively updating lock state entries

In order to update only specific modules of a configuration, you can use the `--update-locks` command line flag.
It takes a comma (`,`) separated list of module notations.
In this mode, the existing lock state is still used as input to resolution, filtering out the modules targeted by the update.

----
❯ gradle classes --update-locks org.apache.commons:commons-lang3,org.slf4j:slf4j-api
----

Wildcards, indicated with `*`, can be used in the group or module name. They can be the only character or appear at the end of the group or module respectively.
The following wildcard notation examples are valid:

* `org.apache.commons:*`: will let all modules belonging to group `org.apache.commons` update
* `*:guava`: will let all modules named `guava`, whatever their group, update
* `org.springframework.spring*:spring*`: will let all modules having their group starting with `org.springframework.spring` and name starting with `spring` update

[NOTE]
====
The resolution may cause other module versions to update, as dictated by the Gradle resolution rules.
====

== Disabling dependency locking

. Make sure that the configuration for which you no longer want locking is not configured with locking.
. Remove the file matching the configurations where you no longer want locking.

If you only perform the second step above, then locking will effectively no longer be applied.
However, if that configuration happens to be resolved in the future at a time where lock state is persisted, it will once again be locked.

== Single lock file per project

Gradle now supports an improved lock file format.
The goal is to have only a single lock file per project, which contains the lock state for all configurations of said project.
By default the file is named `gradle.lockfile` and is located inside the project directory.
The lock state for the buildscript itself is found in a file named `buildscript-gradle.lockfile` inside the project directory.

The main benefit is a substantial reduction in the number of lock files compared to the existing format.

This format is experimental and requires opt-in.

[NOTE]
====
The objective is to default to this single lock file per project in Gradle 7.0.
====

The new format can be activated by enabling the matching <<feature_lifecycle#feature_preview, feature preview>>:

.Single lock file per project activation
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/groovy",files="settings.gradle[]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/kotlin",files="settings.gradle.kts[]"]
====

Then with the following dependency declaration and locked configurations:

.Explicit locking
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/groovy",files="build.gradle[tags=locking-explicit]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/kotlin",files="build.gradle.kts[tags=locking-explicit]"]
====

The lockfile will have the following content:

[listing]
.gradle.lockfile
----
include::{samplesPath}/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/groovy/gradle.lockfile[]
----

* Each line still represents a single dependency in the `group:artifact:version` notation
* Each line then lists all configurations that contain the given dependency
* The last line of the file lists all empty configurations, that is configurations known to have no dependencies

=== Migrating to the new file format

Once you have activated the feature preview (see above), you can simply follow the documentation for <<#lock_all_configurations_in_one_build_execution, writing>> or <<#selectively_updating_lock_state_entries, updating>> dependency lock state.

Then after confirming the single lock file per project contains the lock state for a given configuration, the matching per configuration lock file can be removed from `gradle/dependency-locks`.

=== Configuring the per project lock file name and location

When using the single lock file per project, you can configure its name and location.
The main reason for providing this is to enable having a file name that is determined by some project properties, effectively allowing a single project to store different lock state for different execution contexts.
One trivial example in the JVM ecosystem is the Scala version that is often found in artifact coordinates.

.Changing the lock file name
====
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/groovy",files="build.gradle[tags=locking-file-name]"]
include::sample[dir="snippets/userguide/dependencyManagement/dependencyLocking/lockingSingleFilePerProject/kotlin",files="build.gradle.kts[tags=locking-file-name]"]
====

[[locking_limitations]]
== Locking limitations

* Locking cannot yet be applied to source dependencies.

== Nebula locking plugin

This feature is inspired by the https://github.com/nebula-plugins/gradle-dependency-lock-plugin[Nebula Gradle dependency lock plugin].