1*b2fa4294SXin Li# Stardoc Maintainer's Guide 2*b2fa4294SXin Li 3*b2fa4294SXin Li## Updating Jars 4*b2fa4294SXin Li 5*b2fa4294SXin LiStardoc's source code currently lives in the Bazel source tree at 6*b2fa4294SXin Lihttps://github.com/bazelbuild/bazel/tree/master/src/main/java/com/google/devtools/build/skydoc 7*b2fa4294SXin Li 8*b2fa4294SXin LiFor simplicity of use and building, Stardoc bundles two pre-built jars built 9*b2fa4294SXin Lifrom Bazel source: `stardoc_binary.jar` (emits protobuf documentation format) 10*b2fa4294SXin Liand `renderer_binary.jar` (turns the protobuf into markdown). 11*b2fa4294SXin Li 12*b2fa4294SXin LiTo update the jars: 13*b2fa4294SXin Li 14*b2fa4294SXin Li1. Update `io_bazel` repo commit in `WORKSPACE`. Update transitive deps in 15*b2fa4294SXin Li `WORKSPACE` as needed. 16*b2fa4294SXin Li2. run `update-release-binary.sh` 17*b2fa4294SXin Li 18*b2fa4294SXin Li## Making a New Release 19*b2fa4294SXin Li 20*b2fa4294SXin Li1. Update CHANGELOG.md at the top. You may want to use the following template: 21*b2fa4294SXin Li 22*b2fa4294SXin Li-------------------------------------------------------------------------------- 23*b2fa4294SXin Li 24*b2fa4294SXin Li## Release $VERSION 25*b2fa4294SXin Li 26*b2fa4294SXin Li**New Features** 27*b2fa4294SXin Li 28*b2fa4294SXin Li- Feature 29*b2fa4294SXin Li- Feature 30*b2fa4294SXin Li 31*b2fa4294SXin Li**Incompatible Changes** 32*b2fa4294SXin Li 33*b2fa4294SXin Li- Change 34*b2fa4294SXin Li- Change 35*b2fa4294SXin Li 36*b2fa4294SXin Li**Contributors** 37*b2fa4294SXin Li 38*b2fa4294SXin LiName 1, Name 2, Name 3 (alphabetically) 39*b2fa4294SXin Li 40*b2fa4294SXin Li-------------------------------------------------------------------------------- 41*b2fa4294SXin Li 42*b2fa4294SXin Li2. Bump `version` in version.bzl to the new version. 43*b2fa4294SXin Li3. Ensure that the commits for steps 1 and 2 have been merged. All further 44*b2fa4294SXin Li steps must be performed on a single, known-good git commit. 45*b2fa4294SXin Li4. `bazel build //distro` 46*b2fa4294SXin Li5. Copy the `stardoc-$VERSION.tar.gz` tarball to the mirror (you'll need Bazel 47*b2fa4294SXin Li developer gcloud credentials; assuming you are a Bazel developer, you can 48*b2fa4294SXin Li obtain them via `gcloud init`): 49*b2fa4294SXin Li 50*b2fa4294SXin Li``` 51*b2fa4294SXin Ligsutil cp bazel-bin/distro/stardoc-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz 52*b2fa4294SXin Ligsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz" 53*b2fa4294SXin Li``` 54*b2fa4294SXin Li 55*b2fa4294SXin Li6. Run `sha256sum bazel-bin/distro/stardoc-$VERSION.tar.gz`; you'll need the 56*b2fa4294SXin Li checksum for the release notes. 57*b2fa4294SXin Li7. Draft a new release with a new tag named $VERSION in github. Attach 58*b2fa4294SXin Li `stardoc-$VERSION.tar.gz` to the release. For the release notes, use the 59*b2fa4294SXin Li CHANGELOG.md entry plus the following template: 60*b2fa4294SXin Li 61*b2fa4294SXin Li-------------------------------------------------------------------------------- 62*b2fa4294SXin Li 63*b2fa4294SXin Li**WORKSPACE setup** 64*b2fa4294SXin Li 65*b2fa4294SXin LiTo use Stardoc, add the following to your `WORKSPACE` file: 66*b2fa4294SXin Li 67*b2fa4294SXin Li``` 68*b2fa4294SXin Liload("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 69*b2fa4294SXin Li 70*b2fa4294SXin Lihttp_archive( 71*b2fa4294SXin Li name = "io_bazel_stardoc", 72*b2fa4294SXin Li sha256 = "$SHA256SUM", 73*b2fa4294SXin Li urls = [ 74*b2fa4294SXin Li "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz", 75*b2fa4294SXin Li "https://github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz", 76*b2fa4294SXin Li ], 77*b2fa4294SXin Li) 78*b2fa4294SXin Li 79*b2fa4294SXin Liload("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") 80*b2fa4294SXin Li 81*b2fa4294SXin Listardoc_repositories() 82*b2fa4294SXin Li``` 83*b2fa4294SXin Li 84*b2fa4294SXin LiThe load statement and function call after the `io_bazel_stardoc` repository 85*b2fa4294SXin Lidefinition ensure that this repository's dependencies are loaded. 86*b2fa4294SXin Li 87*b2fa4294SXin Li**Using the rules** 88*b2fa4294SXin Li 89*b2fa4294SXin LiSee [the source](https://github.com/bazelbuild/stardoc/tree/$VERSION). 90*b2fa4294SXin Li 91*b2fa4294SXin Li-------------------------------------------------------------------------------- 92*b2fa4294SXin Li 93