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