# Stardoc Maintainer's Guide

## Updating Jars

Stardoc's source code currently 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 two pre-built jars built
from Bazel source: `stardoc_binary.jar` (emits protobuf documentation format)
and `renderer_binary.jar` (turns the protobuf into markdown).

To update the jars:

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.  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)

--------------------------------------------------------------------------------

2.  Bump `version` in version.bzl to the new version.
3.  Ensure that the commits for steps 1 and 2 have been merged. All further
    steps must be performed on a single, known-good git commit.
4.  `bazel build //distro`
5.  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"
```

6.  Run `sha256sum bazel-bin/distro/stardoc-$VERSION.tar.gz`; you'll need the
    checksum for the release notes.
7.  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()
```

The load statement and function call after the `io_bazel_stardoc` repository
definition ensure that this repository's dependencies are loaded.

**Using the rules**

See [the source](https://github.com/bazelbuild/stardoc/tree/$VERSION).

--------------------------------------------------------------------------------