Maintainer guide improvements

docs/maintainers_guide.md

@@ -109,6 +109,23 @@ repository definition ensures that this repository's dependencies are loaded
 (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 @@ echo -n sha256-; cat bazel-bin/distro/stardoc-$VERSION.tar.gz | openssl dgst -sh
 ```
 
 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 @@ echo -n sha256-; cat bazel-bin/distro/stardoc-$VERSION.tar.gz | openssl dgst -sh
     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.
-
---------------------------------------------------------------------------------
+11. Once the Bazel Central Registry PR is merged, uncomment the MODULE.bazel
+    block in the release description.

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"])
 

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(

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"])
 

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.