Maintainer guide improvements (#187)
* Add blurb about repository fetch errors
* Fix BCR text
* Recommend adding a commented MODULE.bazel setup block and uncommenting (easier than copy/pasting it later)
Fixes #186
diff --git a/docs/maintainers_guide.md b/docs/maintainers_guide.md
index 15d4337..ccc045b 100644
--- a/docs/maintainers_guide.md
+++ b/docs/maintainers_guide.md
@@ -109,6 +109,23 @@
(each function call defines additional repositories for Stardoc's dependencies,
which are then used by subsequent load statements).
+Note that `WORKSPACE` files are sensitive to the order of dependencies. If,
+after updating to a newer version of Stardoc, you encounter "not a valid
+maven_install.json file" or other repository fetch errors (example: #186), try
+moving the Stardoc dependency block above or below other dependencies in your
+`WORKSPACE` file.
+
+<!-- Uncomment after updating Stardoc in Bazel Central Registry
+**MODULE.bazel setup**
+
+```starlark
+bazel_dep(name = "stardoc", version = "$VERSION")
+```
+
+For compatibility with `WORKSPACE` setup, add `repo_name = "io_bazel_stardoc"`
+to the `bazel_dep` call.
+-->
+
**Using the rules**
See [the source](https://github.com/bazelbuild/stardoc/tree/$VERSION).
@@ -123,8 +140,7 @@
```
10. Create a PR at [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry)
- to update the registry's versions of bazel_skylib and
- bazel_skylib_gazelle_plugin.
+ to update the registry's versions of Stardoc.
Use https://github.com/bazelbuild/bazel-central-registry/pull/677 as the
model; you will need to update `modules/stardoc/metadata.json` to list the
@@ -137,18 +153,5 @@
subdirectory exactly matches the `MODULE.bazel` file packaged in the
stardoc-$VERSION.tar.gz tarball - or buildkite checks will fail.
-11. Once the Bazel Central Registry PR is merged, insert in the release
- description after the `WORKSPACE` setup section:
-
---------------------------------------------------------------------------------
-
-**MODULE.bazel setup**
-
-```starlark
-bazel_dep(name = "stardoc", version = "$VERSION")
-```
-
-For compatibility with `WORKSPACE` setup, add `repo_name = "io_bazel_stardoc"`
-to the `bazel_dep` call.
-
---------------------------------------------------------------------------------
\ No newline at end of file
+11. Once the Bazel Central Registry PR is merged, uncomment the MODULE.bazel
+ block in the release description.
\ No newline at end of file
diff --git a/stardoc/BUILD b/stardoc/BUILD
index 159ca0e..b6ee9cd 100644
--- a/stardoc/BUILD
+++ b/stardoc/BUILD
@@ -1,6 +1,6 @@
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
-load("//stardoc:stardoc.bzl", "stardoc")
load("@rules_java//java:defs.bzl", "java_binary", "java_import")
+load("//stardoc:stardoc.bzl", "stardoc")
licenses(["notice"])
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index 6a3fbe7..06dbb97 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -14,8 +14,8 @@
"""Starlark rule for stardoc: a documentation generator tool written in Java."""
-load("@rules_java//java:defs.bzl", "java_binary")
load("@bazel_skylib//rules:copy_file.bzl", "copy_file")
+load("@rules_java//java:defs.bzl", "java_binary")
load("//stardoc/private:stardoc.bzl", "stardoc_markdown_renderer", _stardoc = "stardoc")
def stardoc(
diff --git a/test/BUILD b/test/BUILD
index c4f59e3..3c1c284 100644
--- a/test/BUILD
+++ b/test/BUILD
@@ -1,5 +1,5 @@
-load(":stardoc_test.bzl", "self_gen_test", "stardoc_test")
load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load(":stardoc_test.bzl", "self_gen_test", "stardoc_test")
package(default_applicable_licenses = ["//:license"])
diff --git a/test/bzlmod/def.bzl b/test/bzlmod/def.bzl
index 8970cca..632167d 100644
--- a/test/bzlmod/def.bzl
+++ b/test/bzlmod/def.bzl
@@ -14,8 +14,8 @@
"""A simple macro used to test stardoc."""
-load("@my_skylib//rules:write_file.bzl", "write_file")
load("@local_config_platform//:constraints.bzl", "HOST_CONSTRAINTS")
+load("@my_skylib//rules:write_file.bzl", "write_file")
def write_host_constraints(name):
"""Emits the constraints of the host platform to a file.
