1# Skylib Maintainer's Guide 2 3## The Parts of Skylib 4 5* `bzl_library.bzl` - used by almost all rule sets, and thus requiring 6 especial attention to maintaining backwards compatibility. Ideally, it ought 7 to be moved out of Skylib and and into Bazel's bundled `@bazel_tools` repo 8 (see https://github.com/bazelbuild/bazel-skylib/issues/127). 9* Test libraries - `rules/analysis_test.bzl`, `rules/build_test.bzl`, 10 `lib/unittest.bzl`; these are under more active development than the rest of 11 Skylib, because we want to provide rule authors with a good testing story. 12 Ideally, these ought to be moved out of Skylib and evolved at a faster pace. 13* A kitchen sink of utility modules (everything else). Formerly, these 14 features were piled on in a rather haphazard manner. For any new additions, 15 we want to be more conservative: add a feature only if it is widely needed 16 (or was already independently implemented in multiple rule sets), if the 17 interface is unimpeachable, if level of abstraction is not shallow, and the 18 implementation is efficient. 19 20## PR Review Standards 21 22Because Skylib is so widely used, breaking backwards compatibility can cause 23widespread pain, and shouldn't be done lightly. Therefore: 24 251. In the first place, avoid adding insufficiently thought out, insufficiently 26 tested features which will later need to be replaced in a 27 backwards-incompatible manner. See the criteria in README.md. 282. Given a choice between breaking backwards compatibility and keeping it, try 29 to keep backwards compatibility. For example, if adding a new argument to a 30 function, add it to the end of the argument list, so that existing callers' 31 positional arguments continue to work. 323. Keep Skylib out-of-the-box compatible with the current stable Bazel release 33 (ideally - with two most recent stable releases). 34 * For example, when adding a new function which calls the new 35 `native.foobar()` method which was introduced in the latest Bazel 36 pre-release or is gated behind an `--incompatible` flag, use an `if 37 hasattr(native, "foobar")` check to keep the rest of your module (which 38 doesn't need `native.foobar()`) working even when `native.foobar()` is 39 not available. 40 41In addition, make sure that new code is documented and tested. 42 43If a PR changes any docstring in an existing module, the corresponding 44`stardoc_with_diff_test` in `docs` will fail. To fix the test, ask the PR 45author to run `bazel run //docs:update`. 46 47If a PR adds a new module, make sure that the PR also adds a corresponding 48`stardoc_with_diff_test` target in `docs/BUILD` and a corresponding `*doc.md` 49file under `docs` (generated by `bazel run //docs:update`). 50 51## Making a New Release 52 531. Update CHANGELOG.md at the top. You may want to use the following template: 54 55-------------------------------------------------------------------------------- 56 57``` 58# Release $VERSION 59 60**New Features** 61 62- Feature 63- Feature 64 65**Incompatible Changes** 66 67- Change 68- Change 69 70**Contributors** 71 72Name 1, Name 2, Name 3 (alphabetically from `git log`) 73``` 74 75-------------------------------------------------------------------------------- 76 772. Bump `version` in version.bzl, MODULE.bazel, *and* gazelle/MODULE.bazel to 78 the new version. 79 TODO(#386): add a test to make sure all the versions are in sync. 803. Ensure that the commits for steps 1 and 2 have been merged. All further 81 steps must be performed on a single, known-good git commit. 824. `bazel build //distribution` 835. Copy the `bazel-skylib-$VERSION.tar.gz` and 84 `bazel-skylib-gazelle-plugin-$VERSION.tar.gz` tarballs to the mirror (you'll 85 need Bazel developer gcloud credentials; assuming you are a Bazel developer, 86 you can obtain them via `gcloud init`): 87 88```bash 89gsutil cp bazel-bin/distribution/bazel-skylib{,-gazelle-plugin}-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/ 90gsutil setmeta -h "Cache-Control: public, max-age=31536000" gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib{,-gazelle-plugin}-$VERSION.tar.gz 91``` 92 936. Obtain checksums for release notes: 94 95```bash 96sha256sum bazel-bin/distribution/bazel-skylib-$VERSION.tar.gz 97sha256sum bazel-bin/distribution/bazel-skylib-gazelle-plugin-$VERSION.tar.gz 98```` 99 1007. Draft a new release with a new tag named $VERSION in github. Attach 101 `bazel-skylib-$VERSION.tar.gz` and 102 `bazel-skylib-gazelle-plugin-$VERSION.tar.gz` to the release. For the 103 release notes, use the CHANGELOG.md entry plus the following template: 104 105-------------------------------------------------------------------------------- 106 107**WORKSPACE setup** 108 109``` 110load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 111 112http_archive( 113 name = "bazel_skylib", 114 sha256 = "$SHA256SUM", 115 urls = [ 116 "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz", 117 "https://github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz", 118 ], 119) 120 121load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") 122 123bazel_skylib_workspace() 124``` 125 126***Additional WORKSPACE setup for the Gazelle plugin*** 127 128```starlark 129http_archive( 130 name = "bazel_skylib_gazelle_plugin", 131 sha256 = "$SHA256SUM_GAZELLE_PLUGIN", 132 urls = [ 133 "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-gazelle-plugin-$VERSION.tar.gz", 134 "https://github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-gazelle-plugin-$VERSION.tar.gz", 135 ], 136) 137 138load("@bazel_skylib_gazelle_plugin//:workspace.bzl", "bazel_skylib_gazelle_plugin_workspace") 139 140bazel_skylib_gazelle_plugin_workspace() 141 142load("@bazel_skylib_gazelle_plugin//:setup.bzl", "bazel_skylib_gazelle_plugin_setup") 143 144bazel_skylib_gazelle_plugin_setup() 145``` 146 147**Using the rules** 148 149See [the source](https://github.com/bazelbuild/bazel-skylib/tree/$VERSION). 150 151-------------------------------------------------------------------------------- 152 1538. Review a PR at [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry) 154 created by Publish-to-BCR plugin. 155 156 Use https://github.com/bazelbuild/bazel-central-registry/pull/403 as the 157 model. 158 1599. Once the Bazel Central Registry PR is merged, insert in the release 160 description after the WORKSPACE setup section: 161 162-------------------------------------------------------------------------------- 163 164**MODULE.bazel setup** 165 166```starlark 167bazel_dep(name = "bazel_skylib", version = "$VERSION") 168``` 169 170And for the Gazelle plugin: 171 172```starlark 173bazel_dep(name = "bazel_skylib_gazelle_plugin", version = "$VERSION", dev_dependency = True) 174``` 175 176-------------------------------------------------------------------------------- 177