Update docs for version 7.0.0, remove old APIs (#1703)

* Update docs for version 7.0.0, remove old APIs

Describes the new `scala_toolchains()` API, breaking changes, Bazel
compatibility matrix, and breaking of the `io_bazel_rules_scala` repo
name dependency. Part of #1482, #1647, #1652, and #1699, it also removes
obsolete `WORKSPACE` APIs in favor of `scala_toolchains()`, et. al.

Much of the README text regarding `WORKSPACE` configuration, Bazel
compatibility, and breaking changes comes from:

- #1482 (comment)

The "Breaking changes in `rules_scala` 7.x" section of `README.md`
describes the removed `WORKSPACE` macros, and provides guidance for
adopting the `scala_toolchains()` API. Also includes information about
the upcoming Bzlmod implementation (#1482) and the Bazel 8 compatibility
changes for `rules_scala` 8.x (#1652).

Contains a light editing pass over almost every Markdown file to resolve
`markdownlint` warnings when editing in VSCode. Also added
`.markdownlint.json` to silence rule `MD033/no-inline-html`, since
several docs contain `<br/>` and/or `<table>` elements.

- https://github.com/DavidAnson/vscode-markdownlint?tab=readme-ov-file#markdownlintconfig

Performed other opportunistic grammar edits and added new information,
including:

- `docs/coverage.md`: Describes how to determine the default JaCoCo
  version used by `rules_java`

- `scripts/README.md`: Updates `create_repository.py` docs extensively,
  and adds a section for `sync_bazelversion.sh`

- Replaces `starlark` code fences with `py`, since the syntax is
  identical and editors seem to support it better.

---

Since the next major release is imminent, ensuring the documentation
accurately reflects all the changes since v6.6.0 has become an urgent
priority.

Rather than leave the old `WORKSPACE` APIs in place, which could lead to
surprising failures, this change removes all of them. This also changes
some code that still depended on some of these obsolete macros,
including `scala_toolchains()`. Since all the toolchainization changes
led to the entire project already using `scala_toolchains()` and
`scala_register_toolchains()` exclusively, this proved a low risk
refactoring.

With some Bzlmod and Bazel 8 information already in place, very little
will need to change when these implementations land. The commits that
contain those implementations will also include their relevant
documentation updates.

* Update GitHub refs, minor grammar error in README

It seems the README won't expand refs like #1482. This updates such refs
to use the repo prefix, e.g., #1482.

* More small README.md improvements

* s/stanza/snippet/g

Thanks to @bartoszkosiorek for pointing out in #1703 that "stanza" isn't
a common word. That was my former English Lit major innie leaking out,
applying a poetry term (a group of lines, like a paragraph) out of
context.

* Add Bzlmod repo scope change, `scala_toolchain`

Explicitly notes that some `rules_scala` APIs may break, specifically
`setup_scala_toolchain`. Part of #1482.

Brought to my attention by @michalbogacz in a `#scala` thread in the
Bazel Slack workspace, which was in the context of
michalbogacz/scala-bazel-monorepo#26.

- https://bazelbuild.slack.com/archives/CDCKJ2KFZ/p1740144886159909

* Update README.md per @grepwood's feedback in #1703

- Updates links not to use code tags, since it gives the appearance of
  multiple adjacent links.

- Updates issue reference missing the `bazelbuild/rules_scala` prefix.

- Moves paragraphs above "Getting started" `WORKSPACE` snippet to a new
  "Important changes in `rules_scala` v7.0.0 configuration" section
  following the snippet.

* Update `scala_toolchains()` docstring

Removes the reference to `@rules_scala_toolchains`, since that's not
really a public interface detail.

Prompted by a ping from @gergelyfabian in a Bazel Slack workspace direct
message, asking about the docstring currently reflected on `master`.

* Fix `WORKSPACE` snippet for `rules_java` 7.x

The `WORKSPACE` snippet in the `README.md` now matches what's currently
in all the other `WORKSPACE` files.

I'd previously included the `rules_java` 8.x statements from my Bazel 8
compatibility branch in the `README.md` changes for `rules_scala` 7.x.
@gergelyfabian tried the previous snippet from #1703, and it broke his
build:

- #1703 (comment)

* Clean up cross-compilation.md, rm deprecated attr

Includes a full editing pass over `docs/cross-compilation.md` and
removes the `incompatible_use_toolchain_transition` attribute, which
has been deprecated since before Bazel 6.5.0.

- https://bazel.build/versions/6.4.0/rules/lib/globals?hl=en#rule

The "Cross-build support tiers" could use extra review by someone more
knowledgable about that aspect of `rules_scala`.

Prompted by a suggestion by @gergelyfabian in #1703 to update a single
line, but turned into a complete overhaul.

* Fix `io_bazel_rules_scala`, version in README

Removes a remaining, incorrect `@io_bazel_rules_scala` reference in
`README.md`, as well as in the `.github/workflows/workspace_snippet.sh` script.
Updates the `README.md` to use `<VERSION>` in place of `7.0.0` in the
`WORKSPACE` snippet under "Getting started".

Prompted by a couple comments by @gergelyfabian in #1703. I used the following
command to confirm no more unintentional `io_bazel_rules_scala` references
remain. (I'm leaving the `test_intellij_aspect.sh` script alone for now.)

```txt
$ git ls-files | xargs grep 'io_bazel_rules_scala[^_]'

.github/workflows/workspace_snippet.sh:    name = "rules_scala",  # Can be "io_bazel_rules_scala" if you still need it.
README.md:    name = "rules_scala",  # Can be "io_bazel_rules_scala" if you still need it.
README.md:- __`rules_scala` no longer requires the `io_bazel_rules_scala` repository
test_intellij_aspect.sh:  bazel test --test_output=errors --override_repository io_bazel_rules_scala="${rules_scala_dir}"  --extra_toolchains=@io_bazel_rules_scala//scala:default_toolchain //aspect/testing/tests/src/com/google/idea/blaze/aspect/scala/...
```

There are still many `io_bazel_rules_scala_.*` references, most of them for
internal toolchain dependency repos. The `@io_bazel_rules_scala_config`
repository is the exception, which is a publicly documented interface. (We
_could_ change it, as another potential known breakage for `rules_scala`
v7.0.0.)

* Remove `testing` parameter from `scala_toolchains`

Removed in favor of using the existing `scalatest`, `junit`, and
`specs2` parameters at @simuons's suggestion in:

- #1482 (comment)

Also updated the `scala_toolchains()` docstring slightly and added `doc`
parameters to the `attrs` for `_scala_toolchains_repo()`.

Author: mbland

.github/workflows/workspace_snippet.sh

@@ -19,7 +19,7 @@ Paste this snippet into your \`WORKSPACE\` file:
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
 http_archive(
-    name = "io_bazel_rules_scala",
+    name = "rules_scala",  # Can be "io_bazel_rules_scala" if you still need it.
     sha256 = "${SHA}",
     strip_prefix = "${PREFIX}",
     url = "https://github.com/bazelbuild/rules_scala/releases/download/${TAG}/${ARCHIVE}",

.markdownlint.json

@@ -0,0 +1,5 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false
+}

README.md

@@ -5,7 +5,11 @@ load("//scala:deps.bzl", "rules_scala_dependencies")
 
 rules_scala_dependencies()
 
-load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains")
+load(
+    "@rules_java//java:repositories.bzl",
+    "rules_java_dependencies",
+    "rules_java_toolchains",
+)
 
 rules_java_dependencies()
 
@@ -51,9 +55,11 @@ load("//scala:toolchains.bzl", "scala_register_toolchains", "scala_toolchains")
 scala_toolchains(
     fetch_sources = True,
     jmh = True,
+    junit = True,
     scala_proto = True,
     scalafmt = True,
-    testing = True,
+    scalatest = True,
+    specs2 = True,
     twitter_scrooge = True,
 )
 

WORKSPACE

@@ -1,18 +1,18 @@
-## Coverage support
+# Coverage support
 
-### Running tests with coverage
+## Running tests with coverage
 
 rules_scala supports coverage:
 
-```
+```txt
 bazel coverage //...
 ```
 
 It will produce several .dat files with results for your targets.
 
 You can also add more options to receive a combined coverage report:
 
-```
+```txt
 bazel coverage \
   --combined_report=lcov \
   --coverage_report_generator="@bazel_tools//tools/test/CoverageOutputGenerator/java/com/google/devtools/coverageoutputgenerator:Main" \
@@ -21,18 +21,18 @@ bazel coverage \
 
 This should produce a single `bazel-out/_coverage/_coverage_report.dat` from all coverage files that are generated.
 
-### Processing coverage reports
+## Processing coverage reports
 
-You can install `lcov` package (that supports the format Bazel uses for coverage reports) to have access to additional tools:
+You can install the [`lcov`](https://github.com/linux-test-project/lcov) package (that supports the format Bazel uses for coverage reports) to have access to additional tools:
 
-```
+```txt
 # Use your system package manager. E.g. on Ubuntu:
 sudo apt install lcov
 ```
 
 Having `lcov` package installed you can extract information from your coverage reports:
 
-```
+```txt
 # For a summary:
 lcov --summary your-coverage-report.dat
 # For details:
@@ -55,26 +55,78 @@ echo "coverage report at file://${destdir}/index.html"
 
 ```
 
-### Support for testing frameworks
+## Support for testing frameworks
 
 Coverage support has been only tested with [ScalaTest](http://www.scalatest.org/).
 
-### Working around missing lambda coverage with Scala 2.12+
+## JaCoCo
 
-The current Jacoco version in Bazel (0.8.3) has missing coverage for lambdas
-(including for comprehensions; see issue https://github.com/bazelbuild/rules_scala/issues/1056). Also, the support for
-filtering out code generated by the Scala compiler is quite reduced in Jacoco.
+`rules_scala` uses the [JaCoCo](https://www.jacoco.org/jacoco/) library imported
+by the underlying [`rules_java`](https://github.com/bazelbuild/rules_java)
+module to generate code coverage. `rules_java`, in turn, imports JaCoCo via the
+[`java_tools`](https://github.com/bazelbuild/java_tools) repository, built from
+the [tools/jdk/BUILD.java_tools](
+https://github.com/bazelbuild/bazel/blob/master/tools/jdk/BUILD.java_tools) file
+and [third_party/java/jacoco](
+https://github.com/bazelbuild/bazel/blob/master/third_party/java/jacoco/BUILD)
+package in the Bazel source. `java_tools` and `rules_java` are released more
+frequently than Bazel itself, decoupling them from the Bazel release cycle.
 
-This can be worked around by building a fixed version of Jacoco yourselves (including backported fixes from 0.8.5) and reconfiguring your
-build to use that one instead of the default `jacocorunner`.
+To check the version of JaCoCo used by a specific version of `rules_java`:
 
-You can build jacocorunner with a script in `scripts/build_jacocorunner/build_jacocorunner.sh` (see comments there for more explanation and options).
+- Open [`java/repositories.bzl` in the `rules_java` source](
+    https://github.com/bazelbuild/rules_java/blob/master/java/repositories.bzl).
+
+- Select a specific version of `rules_java` using the **Switch branches/tabs**
+    dropdown menu.
+
+  - Alternatively, replace `master` with the `rules_java` version in the
+      `java/repositories.bzl` URL.
+
+- Make note of the version of `java_tools` specified in the `JAVA_TOOLS_CONFIG`
+    dictionary. For example, [`rules_java` 8.9.0 uses `java_tools` v.13.16](
+    https://github.com/bazelbuild/rules_java/blob/8.9.0/java/repositories.bzl#L49).
+
+- Download the `java_tools` archive using the archive URL:
+
+    ```txt
+    curl -LO https://mirror.bazel.build/bazel_java_tools/releases/java/v13.16/java_tools-v13.16.zip
+    ```
+
+- Unzip the archive, then inspect the top level `BUILD` file:
 
-An older version of this script (for Bazel 4) can be found in `scripts/build_jacocorunner/build_jacocorunner_bazel_4.0.sh`.
+    ```sh
+    $ grep 'jacoco\.core-' BUILD
+
+        jars = ["java_tools/third_party/java/jacoco/org.jacoco.core-0.8.11.jar"],
+        srcjar = "java_tools/third_party/java/jacoco/org.jacoco.core-0.8.11-sources.jar",
+        srcs = ["java_tools/third_party/java/jacoco/org.jacoco.core-0.8.11.jar"],
+    ```
+
+| `rules_java` version | `java_tools` version | JaCoCo version |
+| :-: | :-: | :-: |
+| [8.9.0](https://github.com/bazelbuild/rules_java/blob/8.9.0/java/repositories.bzl#L49) | v13.16 | [0.8.11][JaCoCo version] |
+| [7.12.4](https://github.com/bazelbuild/rules_java/blob/7.12.4/java/repositories.bzl#L49) | v13.9 | [0.8.11][JaCoCo version] |
+
+For information on updating the [JaCoCo version][] used by `rules_java`,
+`java_tools`, and Bazel, see [Bazel's "Upgrading Jacoco version"
+README](
+https://github.com/bazelbuild/bazel/blob/master/third_party/java/jacoco/README.md).
+
+[JaCoCo version]: https://www.jacoco.org/jacoco/trunk/doc/changes.html
+
+## Working around missing JaCoCo features
+
+The version of JaCoCo that ships with `rules_java` may lack support for newer
+Scala features. To work around this, build an updated version of JaCoCo and
+configure the project to use this new artifact instead of the default
+`jacocorunner`.
+
+You can build jacocorunner with a script in `scripts/build_jacocorunner/build_jacocorunner.sh` (see comments there for more explanation and options).
 
 Then, you can use the `jacocorunner` property of `scala_toolchain` to provide the jacocorunner you have built:
 
-```
+```py
 # Example contents of coverage_local_jacocorunner/BUILD
 scala_toolchain(
     name = "local_jacocorunner_toolchain_impl",
@@ -85,7 +137,7 @@ scala_toolchain(
 toolchain(
     name = "local_jacocorunner_scala_toolchain",
     toolchain = "local_jacocorunner_toolchain_impl",
-    toolchain_type = "@io_bazel_rules_scala//scala:toolchain_type",
+    toolchain_type = "@rules_scala//scala:toolchain_type",
     visibility = ["//visibility:public"],
 )
 
@@ -100,15 +152,15 @@ keeping binaries in your repository).
 
 Finally, provide the `scala_toolchain` in your `.bazelrc` or as an option to `bazel coverage`:
 
-```
+```txt
 coverage --extra_toolchains="//coverage_local_jacocorunner:local_jacocorunner_scala_toolchain"
 ```
 
 You could also register the toolchain in your `WORKSPACE`.
 
 You can verify that the locally built `jacocorunner` works with `manual_test/coverage_local_jacocorunner/test.sh`.
 
-#### Notes
+## Notes
 
 Please ensure these scripts use Java 8.