Add Upgrade Note for Strongly Typed Dependencies in Test Suites

subprojects/docs/src/docs/userguide/jvm/jvm_test_suite_plugin.adoc

@@ -95,6 +95,7 @@ Common values are available as constants in link:{javadocPath}/org/gradle/api/at
 
 Here are several examples to illustrate the configurability of test suites.
 
+[[sec:declare_an_additional_test_suite]]
 == Declare an additional test suite
 ====
 include::sample[dir="snippets/testing/test-suite-plugin/groovy",files="build.gradle[tags=configure-testing-extension]"]
@@ -221,6 +222,7 @@ include::sample[dir="snippets/testing/test-suite-multi-configure-each-extracted/
 <2> Apply the closure to a test suite, using the default (`test`) test suite
 <3> Alternate means of applying a configuration closure to a test suite outside of its declaration, using the `integrationTest` test suite
 
+[[sec:differences_with_top_level_dependencies]]
 == Differences between the test suite `dependencies` and the top-level `dependencies` blocks
 
 Gradle 7.6 changed the API of the test suite's `dependencies` block to be more strongly-typed.

subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc

@@ -117,6 +117,59 @@ PMD has been updated to https://pmd.github.io/pmd-6.48.0/pmd_release_notes.html[
 When configuring an executable explicitly for link:{groovyDslPath}/org.gradle.api.tasks.compile.ForkOptions.html#org.gradle.api.tasks.compile.ForkOptions:executable[`JavaCompile`] or link:{groovyDslPath}/org.gradle.api.tasks.testing.Test.html#org.gradle.api.tasks.testing.Test:executable[`Test`] tasks, Gradle will now emit an error if this executable does not exist.
 In the past, the task would be executed with the default toolchain or JVM running the build.
 
+==== Changes to dependency declarateions in Test Suites
+
+As part of the ongoing effort to improve Test Suites, dependency declarations using its nested `dependencies` block are <<jvm_test_suite_plugin.adoc#sec:differences_with_top_level_dependencies, now strongly typed>>.
+This will help make this incubating API more discoverable and easier to use in an IDE.
+
+In some case, this requires syntax changes.
+For example, build scripts that previously added Test Suite dependencies with the following syntax:
+
+```kotlin
+testing {
+  suites {
+    register<JvmTestSuite>("integrationTest") {
+      dependencies {
+        implementation(project)
+      }
+    }
+  }
+}
+```
+
+will now fail to compile, with a message like:
+
+```
+None of the following functions can be called with the arguments supplied:
+public operator fun DependencyAdder.invoke(dependencyNotation: CharSequence): Unit defined in org.gradle.kotlin.dsl
+public operator fun DependencyAdder.invoke(dependency: Dependency): Unit defined in org.gradle.kotlin.dsl
+public operator fun DependencyAdder.invoke(files: FileCollection): Unit defined in org.gradle.kotlin.dsl
+public operator fun DependencyAdder.invoke(dependency: Provider<out Dependency>): Unit defined in org.gradle.kotlin.dsl
+public operator fun DependencyAdder.invoke(externalModule: ProviderConvertible<out MinimalExternalModuleDependency>): Unit defined in org.gradle.kotlin.dsl
+```
+
+To fix this, replace the reference to `project` with a call to `project()`:
+
+```kotlin
+testing {
+  suites {
+    register<JvmTestSuite>("integrationTest") {
+      dependencies {
+        implementation(project())
+      }
+    }
+  }
+}
+```
+
+There are other related changes, such as:
+
+- You cannot use `Provider<String>` as a dependency declaration.
+- You cannot use a `Map` as a dependency declaration for Kotlin or Java.
+- You cannot use a bundle as a dependency declaration directly (`implementation(libs.bundles.testing)`), instead you have to use `implementation.bundle(libs.bundles.testing)`.
+
+For more information, see the updated <<jvm_test_suite_plugin.adoc#sec:declare_an_additional_test_suite, declare an additional test suite>> example in the JVM Test Suite Plugin section of the user guide and the link:{groovyDslPath}/org.gradle.api.artifacts.dsl.DependencyAdder.html[`DependencyAdder`] page in the DSL reference.
+
 === Deprecations
 
 [[invalid_toolchain_specification_deprecation]]