<commit_before>The Gradle team is pleased to announce Gradle 4.6.

First and foremost, this release of Gradle features extensive improvements to dependency management. You can now [declare dependency constraints for transitive dependencies](#dependency-constraints-for-transitive-dependencies) and avoid problems caused by oft-hidden upstream dependency changes. 

This release of Gradle also includes crucial experimental features for Maven dependency compatibility: support for [importing BOMs](#experimental-bom-import), [optional dependencies](#experimental-support-for-optional-dependencies-in-pom-consumption), and [compile/runtime separation when consuming POMs](#experimental-compile/runtime-scope-separation-in-pom-consumption). You can enable these experimental features by adding `enableFeaturePreview('IMPROVED_POM_SUPPORT')` to your _settings.gradle_ or _settings.gradle.kts_ file. Please try these features so they can be promoted to stable for Gradle 5.0 later this year.

Next, this release of Gradle includes built-in support for JUnit Platform and the JUnit Jupiter/Vintage Engine, also known as [JUnit 5 support](#junit-5-support). You can use the new filtering and engines functionality in JUnit 5 using the examples provided below and in the documentation.

Also regarding testing, you can now improve your testing feedback loop when running JVM-based tests using the [new fail-fast option for `Test` tasks](#fail-fast-option-for-test-tasks), which stops the build immediately after the first test failure.

This version of Gradle also comes with a couple especially useful new APIs for task development. You can now [declare custom command-line flags for your custom tasks](#tasks-api-allows-custom-command-line-options), for example: `gradle myCustomTask --myfoo=bar`. In addition, [tasks that extend `Test`, `JavaExec` or `Exec` can declare rich arguments](#rich-command-line-arguments-for-test,-javaexec-or-exec-tasks) for invoking the underlying executable. This allows for better modeling of tools like annotation processors.

Speaking of annotation processors, it is now more convenient to declare dependencies that are annotation processors through the [new `annotationProcessor` dependency configuration](#convenient-declaration-of-annotation-processor-dependencies). Using a separate dependency configuration for annotation processors is a best practice for improving performance.

[Kotlin DSL v0.15.6](https://github.com/gradle/kotlin-dsl/releases/tag/v0.15.6) is included in this release of Gradle, and features  initialization scripts support, nicer script compilation error reporting, performance improvements, and better IntelliJ IDEA integration. Details are available in the linked release notes.

We hope you will build happiness with Gradle 4.6, and we look forward to your feedback via [Twitter](https://twitter.com/gradle) or on [GitHub](https://github.com/gradle).

## Upgrade instructions

Switch your build to use Gradle 4.6 RC1 quickly by updating your wrapper properties:

`gradle wrapper --gradle-version=4.6-rc-1`

Standalone downloads are available at [gradle.org/release-candidate](https://gradle.org/release-candidate). 

## New and noteworthy

Here are the new features introduced in this Gradle release.

### Dependency constraints for transitive dependencies

With [dependency constraints](userguide/managing_transitive_dependencies.html#sec:dependency_constraints), Gradle adds a mechanism to express constraints over transitive dependencies which are used during dependency resolution. In the future, Gradle will also allow you to publish dependency constraints when using the [Gradle module metadata format](https://github.com/gradle/gradle/blob/master/subprojects/docs/src/docs/design/gradle-module-metadata-specification.md) that is currently under development and, as a library author, you will then be able to share these constraints with your library's consumers - making them an appealing alternative to other existing mechanisms for managing transitive dependencies in Gradle.

    dependencies {
        implementation 'org.apache.httpcomponents:httpclient'
    }

    dependencies {
        constraints {
            // declare versions for my dependencies in a central place
            implementation 'org.apache.httpcomponents:httpclient:4.5.3'
            // declare versions for transitive dependencies
            implementation 'commons-codec:commons-codec:1.11'
        }
    }

In the example, the version of `commons-codec` that is brought in transitively is `1.9`. With the constraint, we express that we need at least `1.11` and Gradle will now pick that version during dependency resolution.

### Experimental BOM import

Gradle now [provides support](userguide/managing_transitive_dependencies.html#sec:bom_import) for importing [bill of materials (BOM) files](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Importing_Dependencies), which are effectively `.pom` files that use `<dependencyManagement>` to control the dependency versions of direct and transitive dependencies. It works by declaring a dependency on a BOM.

    dependencies {
        // import a BOM
        implementation 'org.springframework.boot:spring-boot-dependencies:1.5.8.RELEASE'
    
        // define dependencies without versions
        implementation 'com.google.code.gson:gson'
        implementation 'dom4j:dom4j'
    }

Here, for example, the versions of `gson` and `dom4j` are provided by the Spring Boot BOM.

_Note:_ This is a _Gradle 5.0 feature preview_, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding `enableFeaturePreview('IMPROVED_POM_SUPPORT')` in _settings.gradle_.

### Experimental support for optional dependencies in POM consumption

Gradle now creates a dependency constraint for each dependency declaration in a POM file with `<optional>true</optional>`. This constraint will produce the expected result for an optional dependency: if the dependency module is brought in by another, non-optional dependency declaration, then the constraint will apply when choosing the version for that dependency (e.g., if the optional dependency defines a higher version, that one is chosen).

_Note:_ This is a _Gradle 5.0 feature preview_, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding `enableFeaturePreview('IMPROVED_POM_SUPPORT')` in _settings.gradle_.

### Experimental compile/runtime scope separation in POM consumption

Since Gradle 1.0, `runtime` scoped dependencies have been included in the Java compile classpath, which has some drawbacks:

- The compile classpath is much larger than it needs to be, slowing down compilation.
- The compile classpath includes `runtime` files that do not impact compilation, resulting in unnecessary re-compilation when these files change.

Now, if this new behavior is turned on, the Java and Java Library plugins both honor the separation of compile and runtime scopes. Meaning that the compile classpath only includes `compile` scoped dependencies, while the runtime classpath adds the `runtime` scoped dependencies as well. This is in particular useful if you develop and publish Java libraries with Gradle where the api/implementation dependencies separation is reflected in the published scopes.

_Note:_ This is a _Gradle 5.0 feature preview_, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding `enableFeaturePreview('IMPROVED_POM_SUPPORT')` in _settings.gradle_.

### JUnit 5 support

[JUnit 5](http://junit.org/junit5/docs/current/user-guide) is the latest version of the well-known `JUnit` test framework. JUnit 5 is composed of several modules:

> JUnit 5 = JUnit Platform + JUnit Jupiter + JUnit Vintage
    
The `JUnit Platform` serves as a foundation for launching testing frameworks on the JVM. `JUnit Jupiter` is the combination of the new [programming model](http://junit.org/junit5/docs/current/user-guide/#writing-tests)
 and [extension model](http://junit.org/junit5/docs/current/user-guide/#extensions) for writing tests and extensions in JUnit 5. `JUnit Vintage` provides a `TestEngine` for running JUnit 3 and JUnit 4 based tests on the platform.
    
Gradle now provides native support for `JUnit Jupiter/Vintage Engine` on top of `JUnit Platform`. To enable `JUnit Platform` support, you just need to add one line to your `build.gradle`:

    test {
        useJUnitPlatform()
    }

Moreover, [Tagging and Filtering](http://junit.org/junit5/docs/current/user-guide/#writing-tests-tagging-and-filtering) can be enabled via:

    test {
        useJUnitPlatform {
            // includeTags 'fast'
            excludeTags 'slow'
            
            // includeEngines 'junit-jupiter', 'junit-vintage'
            // excludeEngines 'custom-engine'
        }
    }
    
You can find more information on [test grouping and filtering in the Java Plugin documentation](userguide/java_plugin.html#test_grouping).
    
#### JUnit Jupiter Engine
    
To enable `JUnit Jupiter` support, add the following dependencies:

    dependencies {
        testImplementation 'org.junit.jupiter:junit-jupiter-api:5.0.3'
        testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.0.3'
    }      <commit_msg>Do not document new feature previews as experimental, they are incubating but with known backward compat breakage<commit_after>The Gradle team is pleased to announce Gradle 4.6.

First and foremost, this release of Gradle features extensive improvements to dependency management. You can now [declare dependency constraints for transitive dependencies](#dependency-constraints-for-transitive-dependencies) and avoid problems caused by oft-hidden upstream dependency changes. 

This release of Gradle also includes crucial features for Maven dependency compatibility: support for [importing BOMs](#experimental-bom-import), [optional dependencies](#experimental-support-for-optional-dependencies-in-pom-consumption), and [compile/runtime separation when consuming POMs](#experimental-compile/runtime-scope-separation-in-pom-consumption). For now you must enable these features by adding `enableFeaturePreview('IMPROVED_POM_SUPPORT')` to your _settings.gradle_ file, as they break backward compatibility in some cases.

Next, this release of Gradle includes built-in support for JUnit Platform and the JUnit Jupiter/Vintage Engine, also known as [JUnit 5 support](#junit-5-support). You can use the new filtering and engines functionality in JUnit 5 using the examples provided below and in the documentation.

Also regarding testing, you can now improve your testing feedback loop when running JVM-based tests using the [new fail-fast option for `Test` tasks](#fail-fast-option-for-test-tasks), which stops the build immediately after the first test failure.

This version of Gradle also comes with a couple especially useful new APIs for task development. You can now [declare custom command-line flags for your custom tasks](#tasks-api-allows-custom-command-line-options), for example: `gradle myCustomTask --myfoo=bar`. In addition, [tasks that extend `Test`, `JavaExec` or `Exec` can declare rich arguments](#rich-command-line-arguments-for-test,-javaexec-or-exec-tasks) for invoking the underlying executable. This allows for better modeling of tools like annotation processors.

Speaking of annotation processors, it is now more convenient to declare dependencies that are annotation processors through the [new `annotationProcessor` dependency configuration](#convenient-declaration-of-annotation-processor-dependencies). Using a separate dependency configuration for annotation processors is a best practice for improving performance.

[Kotlin DSL v0.15.6](https://github.com/gradle/kotlin-dsl/releases/tag/v0.15.6) is included in this release of Gradle, and features  initialization scripts support, nicer script compilation error reporting, performance improvements, and better IntelliJ IDEA integration. Details are available in the linked release notes.

We hope you will build happiness with Gradle 4.6, and we look forward to your feedback via [Twitter](https://twitter.com/gradle) or on [GitHub](https://github.com/gradle).

## Upgrade instructions

Switch your build to use Gradle 4.6 RC1 quickly by updating your wrapper properties:

`gradle wrapper --gradle-version=4.6-rc-1`

Standalone downloads are available at [gradle.org/release-candidate](https://gradle.org/release-candidate). 

## New and noteworthy

Here are the new features introduced in this Gradle release.

### Dependency constraints for transitive dependencies

With [dependency constraints](userguide/managing_transitive_dependencies.html#sec:dependency_constraints), Gradle adds a mechanism to express constraints over transitive dependencies which are used during dependency resolution. 

In the future, Gradle will also allow you to _publish_ dependency constraints when using the [Gradle module metadata format](https://github.com/gradle/gradle/blob/master/subprojects/docs/src/docs/design/gradle-module-metadata-specification.md) (currently under development) such that library authors will be able to share these constraints with library consumers. This makes dependency constraints a better alternative over other existing mechanisms for managing transitive dependencies in Gradle.

    dependencies {
        implementation 'org.apache.httpcomponents:httpclient'
    }

    dependencies {
        constraints {
            // declare versions for my dependencies in a central place
            implementation 'org.apache.httpcomponents:httpclient:4.5.3'
            // declare versions for transitive dependencies
            implementation 'commons-codec:commons-codec:1.11'
        }
    }

In the example, the version of `commons-codec` that is brought in transitively is `1.9`. With the constraint, we express that we need at least `1.11` and Gradle will now pick that version during dependency resolution.

### BOM import

Gradle now [provides support](userguide/managing_transitive_dependencies.html#sec:bom_import) for importing [bill of materials (BOM) files](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Importing_Dependencies), which are effectively `.pom` files that use `<dependencyManagement>` to control the dependency versions of direct and transitive dependencies. It works by declaring a dependency on a BOM.

    dependencies {
        // import a BOM
        implementation 'org.springframework.boot:spring-boot-dependencies:1.5.8.RELEASE'
    
        // define dependencies without versions
        implementation 'com.google.code.gson:gson'
        implementation 'dom4j:dom4j'
    }

Here, for example, the versions of `gson` and `dom4j` are provided by the Spring Boot BOM.

**Note:** This is a _Gradle 5.0 feature preview_, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding `enableFeaturePreview('IMPROVED_POM_SUPPORT')` in _settings.gradle_.

### Support for optional dependencies in POM consumption

Gradle now creates a dependency constraint for each dependency declaration in a POM file with `<optional>true</optional>`. This constraint will produce the expected result for an optional dependency: if the dependency module is brought in by another, non-optional dependency declaration, then the constraint will apply when choosing the version for that dependency (e.g., if the optional dependency defines a higher version, that one is chosen).

**Note:** This is a _Gradle 5.0 feature preview_, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding `enableFeaturePreview('IMPROVED_POM_SUPPORT')` in _settings.gradle_.

### Compile/runtime scope separation in POM consumption

Since Gradle 1.0, `runtime` scoped dependencies have been included in the Java compile classpath, which has some drawbacks:

- The compile classpath is much larger than it needs to be, slowing down compilation.
- The compile classpath includes `runtime` files that do not impact compilation, resulting in unnecessary re-compilation when these files change.

Now, if this new behavior is turned on, the Java and Java Library plugins both honor the separation of compile and runtime scopes. Meaning that the compile classpath only includes `compile` scoped dependencies, while the runtime classpath adds the `runtime` scoped dependencies as well. This is in particular useful if you develop and publish Java libraries with Gradle where the api/implementation dependencies separation is reflected in the published scopes.

**Note:** This is a _Gradle 5.0 feature preview_, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding `enableFeaturePreview('IMPROVED_POM_SUPPORT')` in _settings.gradle_.

### JUnit 5 support

[JUnit 5](http://junit.org/junit5/docs/current/user-guide) is the latest version of the well-known `JUnit` test framework. JUnit 5 is composed of several modules:

> JUnit 5 = JUnit Platform + JUnit Jupiter + JUnit Vintage

The `JUnit Platform` serves as a foundation for launching testing frameworks on the JVM. `JUnit Jupiter` is the combination of the new [programming model](http://junit.org/junit5/docs/current/user-guide/#writing-tests)
 and [extension model](http://junit.org/junit5/docs/current/user-guide/#extensions) for writing tests and extensions in JUnit 5. `JUnit Vintage` provides a `TestEngine` for running JUnit 3 and JUnit 4 based tests on the platform.
    
Gradle now provides native support for `JUnit Jupiter/Vintage Engine` on top of `JUnit Platform`. To enable `JUnit Platform` support, you just need to add one line to your `build.gradle`:

    test {
        useJUnitPlatform()
    }

Moreover, [Tagging and Filtering](http://junit.org/junit5/docs/current/user-guide/#writing-tests-tagging-and-filtering) can be enabled via:

    test {
        useJUnitPlatform {
            // includeTags 'fast'
            excludeTags 'slow'
            
            // includeEngines 'junit-jupiter', 'junit-vintage'
            // excludeEngines 'custom-engine'
        }
    }
    
You can find more information on [test grouping and filtering in the Java Plugin documentation](userguide/java_plugin.html#test_grouping).
    
#### JUnit Jupiter Engine
    
To enable `JUnit Jupiter` support, add the following dependencies:

    dependencies {
        testImplementation 'org.junit.jupiter:junit-jupiter-api:5.0.3'
        testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.0.3'
    }      
{'fraction_non_alphanumeric': 0.06961355214399154, 'fraction_numerical': 0.008046585494970884, 'mean_word_length': 4.49156976744186, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 11, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1203762', 'n_tokens_mistral': 4835, 'n_tokens_neox': 4567, 'n_words': 2100}