Document validate_scala_version = False

Adds "Disabling Scala version validation when defining a custom Scala
toolchain" under "Breaking changes in `rules_scala` 7.x" in `README.md`.

Adds "Step 3 (optional)" under "Defining your own `scala_toolchain`" in
`docs/scala_toolchain.md`.

Prompted by:
#1710 (comment)

Also fixes a typo and a broken link in `docs/scala_toolchain.md`.

Author: mbland

README.md

@@ -711,6 +711,35 @@ In `WORKSPACE`, this `register_toolchains()` call must come before calling
 `scala_register_toolchains()` to ensure this toolchain takes precedence. The
 same exact call will also work in `MODULE.bazel`.
 
+### Disabling Scala version validation when defining a custom Scala toolchain
+
+When [defining a 'scala_toolchain()' using custom compiler JARs](
+docs/scala_toolchain.md#b-defining-your-own-scala_toolchain), while using
+`scala_toolchains()` to instantiate other builtin toolchains, set
+`validate_scala_version = False`:
+
+```py
+# WORKSPACE
+scala_toolchains(
+    validate_scala_version = False,
+    # ...other toolchain parameters...
+)
+```
+
+This differs from the previous API in two ways that avoided instantiating the
+default Scala compiler JAR repositories, and thus Scala version validation:
+
+- Calling `scala_repositories(load_jar_deps = False)` would instantiate only
+    other `rules_scala` dependency repos (`rules_java`, `protobuf`, etc.) and
+    compiler source JAR repos.
+
+- Calling `rules_scala_setup()` directly, instead of indirectly via
+    `scala_repositories()`, instantiated the other dependency repositories only.
+
+See ["Defining your own scala_toolchain > Step 3 (optional)" from
+docs/scala_toolchain.md](docs/scala_toolchain.md#step-3-optional) for futher
+details.
+
 ### Bzlmod configuration (coming soon!)
 
 The upcoming Bzlmod implementation will funnel through the `scala_toolchains()`

docs/scala_toolchain.md

@@ -25,7 +25,7 @@ scala_toolchains()
 scala_register_toolchains()
 ```
 
-### B) Defining your own `scala_toolchain` requires 2 steps
+### B) Defining your own `scala_toolchain`
 
 #### Step 1
 
@@ -65,7 +65,7 @@ load("@rules_scala//scala:scala.bzl", "setup_scala_toolchain")
 
 setup_scala_toolchain(
     name = "my_toolchain",
-    # configure toolchain dependecies
+    # configure toolchain dependencies
     parser_combinators_deps = [
         "@maven//:org_scala_lang_modules_scala_parser_combinators_2_12",
     ],
@@ -101,6 +101,32 @@ Register your custom toolchain:
 register_toolchains("//toolchains:my_scala_toolchain")
 ```
 
+#### Step 3 (optional)
+
+If you use `scala_toolchains()` to instantiate other builtin toolchains, set
+`validate_scala_version = False`:
+
+```py
+# WORKSPACE
+scala_toolchains(
+    validate_scala_version = False,
+    # ...other toolchain parameters...
+)
+```
+
+This prevents `rules_scala` from checking that the Scala versions specified via
+`scala_config` match the `scala_version` values from
+`third_party/repositories/scala_*.bzl`.
+
+`scala_toolchains()` uses these `scala_*.bzl` files to instantiate dependency
+JAR repositories required by the builtin toolchains. It always instantiates a
+default Scala toolchain, along with its compiler JAR repositories, since [most
+users expect this behavior][1633-comment]. (As always, calling
+`register_toolchains()` on your own toolchain in `MODULE.bazel`, or before
+`scala_register_toolchains()` in `WORKSPACE`, overrides the builtin toolchain.)
+
+[1633-comment]: https://github.com/bazelbuild/rules_scala/pull/1633#discussion_r1834378901
+
 ## Configuration options
 
 The following attributes apply to both `scala_toolchain` and
@@ -168,7 +194,7 @@ The following attributes apply to both `scala_toolchain` and
       <td>
         <p><code>String; optional</code></p>
         <p>
-          Enable unused dependency checking (see <a href="https://github.com/bazelbuild/rules_scala#experimental-unused-dependency-checking">Unused dependency checking</a>).
+          Enable unused dependency checking (see <a href="./dependency-tracking.md#experimental-unused-dependency-checking">Unused dependency checking</a>).
           Possible values are: <code>off</code>, <code>warn</code> and <code>error</code>.
         </p>
       </td>