Stardoc proto definition is vendored from the Bazel source tree at https://github.com/bazelbuild/bazel/tree/master/src/main/protobuf/stardoc_output.proto
To update the proto definition from Bazel's master branch, run update-release-binary.sh
To vendor the proto definition from a particular branch or commit in the Bazel tree, run BAZEL_BRANCH=$BRANCH_OR_SHA ./update-release-binary.sh
setup.bzl
+ WORKSPACE
and MODULE.bazel
.CHANGELOG.md
at the top. You may want to use the following New Features
Incompatible Changes
Contributors
Name 1, Name 2, Name 3 (alphabetically)
Bump version
in version.bzl
and MODULE.bazel
to the new version.
Ensure that the commits for steps 1-3 have been merged. All further steps must be performed on a single, known-good git commit.
bazel build //distro
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"
Obtain checksum for release notes:
sha256sum bazel-bin/distro/stardoc-$VERSION.tar.gz
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:
MODULE.bazel setup
bazel_dep(name = "stardoc", version = "$VERSION")
By default - in other words, when using Bzlmod for dependency management - Stardoc uses @stardoc
as its repo name. The legacy WORSKSPACE
setup (see below) used @io_bazel_stardoc
instead. For compatibility with the legacy WORKSPACE
setup, you may add repo_name = "io_bazel_stardoc"
to the bazel_dep
call.
Legacy 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_java//java:rules_java_deps.bzl", "rules_java_dependencies") rules_java_dependencies() load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") protobuf_deps() 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.
echo -n sha256-; cat bazel-bin/distro/stardoc-$VERSION.tar.gz | openssl dgst -sha256 -binary | base64
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.
Once the Bazel Central Registry PR is merged, uncomment the MODULE.bazel block in the release description.