Merge pull request #9285 from gradle/eskatos/kotlin-dsl/doc-issue-tra…

…cker

 Direct kotlin-dsl issues to gradle/gradle in the kotlin-dsl user guide chapter

subprojects/docs/src/docs/userguide/kotlin_dsl.adoc

@@ -15,7 +15,6 @@
 :kotlin-reference: https://kotlinlang.org/docs/reference/
 :kotlin-tutorials: https://kotlinlang.org/tutorials/
 :kotlin-dsl-samples: https://github.com/gradle/kotlin-dsl/tree/master/samples/
-:kotlin-dsl-issues: https://github.com/gradle/kotlin-dsl/issues/
 :gradle-issues: https://github.com/gradle/gradle/issues/
 :plugin-portal: https://plugins.gradle.org/
 
@@ -130,7 +129,7 @@ If the above doesn't work and you suspect an issue with the Kotlin DSL script ed
 ** `$HOME/Library/Logs/gradle-kotlin-dsl` on Mac OS X
 ** `$HOME/.gradle-kotlin-dsl/logs` on Linux
 ** `$HOME/AppData/Local/gradle-kotlin-dsl/log` on Windows
-* Open an issue on the link:{kotlin-dsl-issues}[Kotlin DSL issue tracker], including as much detail as you can.
+* Open an issue on the link:{gradle-issues}[Gradle issue tracker], including as much detail as you can.
 
 From version 5.1 onwards, the log directory is cleaned up automatically.
 It is checked periodically (at most every 24 hours) and log files are deleted if they haven’t been used for 7 days.
@@ -140,10 +139,7 @@ For IDE problems outside of the Kotlin DSL script editor, please open issues in
 * link:[JetBrains's IDEA issue tracker],
 * link:[Google's Android Studio issue tracker].
 
-Lastly, if you face problems with Gradle itself or with the Kotlin DSL, please open issues on the corresponding issue tracker:
-
-* link:{gradle-issues}[Gradle build tool issue tracker],
-* link:{kotlin-dsl-issues}[Kotlin DSL issue tracker].
+Lastly, if you face problems with Gradle itself or with the Kotlin DSL, please open issues on the link:{gradle-issues}[Gradle issue tracker].
 
 
 [[sec:scripts]]
@@ -720,6 +716,12 @@ All three libraries and their dependencies are bundled with Gradle, so these dep
  * Configures the Kotlin compiler with the same settings that are used for Kotlin DSL scripts, ensuring consistency between your build logic and those scripts.
  * Enables support for <<kotdsl:precompiled_plugins,precompiled script plugins>>.
 
+[CAUTION]
+.Avoid specifying a version for the `kotlin-dsl` plugin
+====
+Each Gradle release is meant to be used with a specific version of the `kotlin-dsl` plugin and compatibility between arbitrary Gradle releases and `kotlin-dsl` plugin versions is not guaranteed. Using an unexpected version of the `kotlin-dsl` plugin in a build will emit a warning and can cause hard to diagnose problems.
+====
+
 This is the basic configuration you need to use the plugin:
 
 .Applying the Kotlin DSL Plugin to a `buildSrc` project
@@ -1021,13 +1023,13 @@ native {                                                    <3>
 [[kotdsl:limitations]]
 == Limitations
 
-* The Kotlin DSL is link:{kotlin-dsl-issues}902[known to be slower than the Groovy DSL] on first use, for example with clean checkouts or on ephemeral continuous integration agents.
+* The Kotlin DSL is link:https://github.com/gradle/kotlin-dsl/issues/902[known to be slower than the Groovy DSL] on first use, for example with clean checkouts or on ephemeral continuous integration agents.
 Changing something in the _buildSrc_ directory also has an impact as it invalidates build-script caching.
 The main reason for this is the slower script compilation for Kotlin DSL.
 * In IntelliJ IDEA, you must link:https://www.jetbrains.com/help/idea/gradle.html#gradle_import[import your project from the Gradle model] in order to get content assist and refactoring support for your Kotlin DSL build scripts.
 * The Kotlin DSL will not support the `model {}` block, which is part of the link:https://blog.gradle.org/state-and-future-of-the-gradle-software-model[discontinued Gradle Software Model].
 However, you _can_ apply model rules from scripts — see the link:{kotlin-dsl-samples}model-rules[model rules] sample for more information.
 * We recommend against enabling the incubating <<multi_project_builds#sec:configuration_on_demand,configuration on demand>> feature as it can lead to very hard-to-diagnose problems.
 
-If you run into trouble or discover a suspected bug, please report the issue in the Kotlin DSL link:{kotlin-dsl-issues}[issue tracker].
+If you run into trouble or discover a suspected bug, please report the issue in the link:{gradle-issues}[Gradle issue tracker].