Stardoc Maintainer's Guide

Updating Proto and Bundled Jar

Stardoc proto definition is vendored from the Bazel source tree at https://github.com/bazelbuild/bazel/tree/master/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto

Stardoc legacy extractor's source code lives in the Bazel source tree at https://github.com/bazelbuild/bazel/tree/master/src/main/java/com/google/devtools/build/skydoc

For simplicity of use and building, Stardoc bundles a pre-built jar for the legacy extractor which is built from Bazel source: stardoc_binary.jar (emits protobuf documentation format).

To update the proto definition and jar:

  1. Update io_bazel repo commit in WORKSPACE. Update transitive deps in WORKSPACE as needed.
  2. run update-release-binary.sh

Making a New Release

  1. Verify tests. Verify that dependencies are consistent between setup.bzl + WORKSPACE and MODULE.bazel (but note that MODULE.bazel does not include dependencies on io_bazel and its transitive deps).
  2. Update CHANGELOG.md at the top. You may want to use the following
    template:

Release $VERSION

New Features

  • Feature
  • Feature

Incompatible Changes

  • Change
  • Change

Contributors

Name 1, Name 2, Name 3 (alphabetically)

  1. Bump version in version.bzl and MODULE.bazel to the new version.

  2. Ensure that the commits for steps 1-3 have been merged. All further steps must be performed on a single, known-good git commit.

  3. bazel build //distro

  4. Copy the stardoc-$VERSION.tar.gz tarball to the mirror (you'll need Bazel developer gcloud credentials; assuming you are a Bazel developer, you can obtain them via gcloud init):

    gsutil cp bazel-bin/distro/stardoc-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz
gsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz"

  5. Obtain checksum for release notes:

    sha256sum bazel-bin/distro/stardoc-$VERSION.tar.gz

  6. Draft a new release with a new tag named $VERSION in github. Attach stardoc-$VERSION.tar.gz to the release. For the release notes, use the CHANGELOG.md entry plus the following template:

WORKSPACE setup

To use Stardoc, add the following to your WORKSPACE file:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "io_bazel_stardoc",
    sha256 = "$SHA256SUM",
    urls = [
        "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz",
        "https://github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz",
    ],
)

load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")

stardoc_repositories()

load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")

rules_jvm_external_deps()

load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")

rules_jvm_external_setup()

load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps")

stardoc_external_deps()

load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")

stardoc_pinned_maven_install()

The sequence of function calls and load statements after the io_bazel_stardoc 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.

Using the rules

See the source.

  1. Obtain Subresource Integrity format checksum for bzlmod:
echo -n sha256-; cat bazel-bin/distro/stardoc-$VERSION.tar.gz | openssl dgst -sha256 -binary | base64

  1. Create a PR at Bazel Central Registry 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 new version in versions, and create new $VERSION subdirectories for the updated module, using the latest existing version subdirectories as the guide. Use Subresource Integrity checksums obtained above in the new source.json file.

    Ensure that the MODULE.bazel file you add in the new $VERSION subdirectory exactly matches the MODULE.bazel file packaged in the stardoc-$VERSION.tar.gz tarball - or buildkite checks will fail.

  2. Once the Bazel Central Registry PR is merged, uncomment the MODULE.bazel block in the release description.