93 lines
3.0 KiB
Markdown
93 lines
3.0 KiB
Markdown
# 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).
|
|
|
|
--------------------------------------------------------------------------------
|
|
|