Document Scala Java bytecode target changes

Fixes #21551

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

@@ -228,6 +228,37 @@ The Scala plugin also modifies some source set properties:
 | `allSource` | Adds all source files found in the Scala source directories.
 |===
 
+[[sec:scala_target]]
+== Target bytecode level and Java APIs version
+
+When running the Scala compile task, Gradle will always add a parameter to configure the Java target for the Scala compiler that is derived from the Gradle configuration:
+
+* When using toolchains, the `-release` option, or `target` for older Scala versions, is selected, with a version matching the Java language level of the toolchain configured.
+* When not using toolchains, Gradle will always pass a `target` flag -- with exact value dependent on the Scala version -- to compile to Java 8 bytecode.
+
+[NOTE]
+====
+This means that using toolchains with a recent Java version and an old Scala version can result in failures because Scala only supported Java 8 bytecode for some time.
+The solution is then to either use the right Java version in the toolchain or explicitly downgrade the target when needed.
+====
+
+The following table explains the values computed by Gradle:
+
+.Scala target parameter based on project configuration
+[%header%autowidth,compact]
+|===
+| Scala version | Toolchain in use | Parameter value
+.2+| version < `2.13.1`                 | yes   | `-target:jvm-1.<java_version>`
+                                        | no    | `-target:jvm-1.8`
+.2+| `2.13.1` \<= version < `2.13.9`    | yes   | `-target:<java_version>`
+                                        | no    | `-target:8`
+.2+| `2.13.9` \<= version < `3.0`       | yes   | `-release:<java_version>`
+                                        | no    | `-target:8`
+.2+| `3.0` \<= version                  | yes   | `-release:<java_version>`
+                                        | no    | `-Xtarget:8`
+|===
+
+Setting any of these flags explicitly, or using flags containing `java-output-version`, on link:{groovyDslPath}/org.gradle.language.scala.tasks.BaseScalaCompileOptions.html#org.gradle.language.scala.tasks.BaseScalaCompileOptions:additionalParameters[`ScalaCompile.scalaCompileOptions.additionalParameters`] disables that logic in favor of the explicit flag.
 
 [[sec:scala_compiling_in_external_process]]
 == Compiling in external process

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

@@ -693,6 +693,13 @@ In case no toolchains are explicitly configured, the toolchain corresponding to
 
 Similarly, tasks from the Groovy and Scala plugins also rely on toolchains to determine on which JVM they are executed.
 
+==== Scala compilation target
+
+With the toolchain changes described above, Scala compilation tasks are now always provided with a `target` or `release` parameter.
+The exact parameter and value depend on toolchain usage, or not, and Scala version.
+
+See the <<scala_plugin#sec:scala_target,Scala plugin documentation>> for details.
+
 [[changes_7.6]]
 == Upgrading from 7.5 and earlier