Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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()`.
- Loading branch information
