mirror of
https://github.com/bazelbuild/bazel-skylib
synced 2024-11-28 08:43:51 +00:00
117 lines
5.1 KiB
Markdown
117 lines
5.1 KiB
Markdown
# Skylib Maintainer's Guide
|
|
|
|
## The Parts of Skylib
|
|
|
|
* `bzl_library.bzl` - used by almost all rule sets, and thus requiring
|
|
especial attention to maintaining backwards compatibility. Ideally, it ought
|
|
to be moved out of Skylib and and into Bazel's bundled `@bazel_tools` repo
|
|
(see https://github.com/bazelbuild/bazel-skylib/issues/127).
|
|
* Test libraries - `rules/analysis_test.bzl`, `rules/build_test.bzl`,
|
|
`lib/unittest.bzl`; these are under more active development than the rest of
|
|
Skylib, because we want to provide rule authors with a good testing story.
|
|
Ideally, these ought to be moved out of Skylib and evolved at a faster pace.
|
|
* A kitchen sink of utility modules (everything else). Formerly, these
|
|
features were piled on in a rather haphazard manner. For any new additions,
|
|
we want to be more conservative: add a feature only if it is widely needed
|
|
(or was already independently implemented in multiple rule sets), if the
|
|
interface is unimpeachable, if level of abstraction is not shallow, and the
|
|
implementation is efficient.
|
|
|
|
## PR Review Standards
|
|
|
|
Because Skylib is so widely used, breaking backwards compatibility can cause
|
|
widespread pain, and shouldn't be done lightly. Therefore:
|
|
|
|
1. In the first place, avoid adding insufficiently thought out, insufficiently
|
|
tested features which will later need to be replaced in a
|
|
backwards-incompatible manner. See the criteria in README.md.
|
|
2. Given a choice between breaking backwards compatibilty and keeping it, try
|
|
to keep backwards compatibility. For example, if adding a new argument to a
|
|
function, add it to the end of the argument list, so that existing callers'
|
|
positional arguments continue to work.
|
|
3. Keep Skylib out-of-the-box compatible with the current stable Bazel release
|
|
(ideally - with two most recent stable releases).
|
|
* For example, when adding a new function which calls the new
|
|
`native.foobar()` method which was introduced in the latest Bazel
|
|
pre-release or is gated behind an `--incompatible` flag, use an `if
|
|
hasattr(native, "foobar")` check to keep the rest of your module (which
|
|
doesn't need `native.foobar()`) working even when `native.foobar()` is
|
|
not available.
|
|
|
|
In addition, make sure that new code is documented and tested.
|
|
|
|
If a PR changes any docstring in an existing module, the corresponding
|
|
`stardoc_with_diff_test` in `docs` will fail. To fix the test, ask the PR
|
|
author to run `bazel run //docs:update`.
|
|
|
|
If a PR adds a new module, make sure that the PR also adds a corresponding
|
|
`stardoc_with_diff_test` target in `docs/BUILD` and a corresponding `*doc.md`
|
|
file under `docs` (generated by `bazel run //docs:update`).
|
|
|
|
## 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 from `git log`)
|
|
|
|
--------------------------------------------------------------------------------
|
|
|
|
2. Bump `version` in version.bzl *and* MODULE.bazel to the new version.
|
|
TODO(#386): add a test to make sure the two versions are in sync.
|
|
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 //distribution:bazel-skylib-$VERSION.tar.gz`
|
|
5. Copy the `bazel-skylib-$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/distribution/bazel-skylib-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz
|
|
gsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz"
|
|
```
|
|
|
|
6. Run `sha256sum bazel-bin/distro/bazel-skylib-$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
|
|
`bazel-skylib-$VERSION.tar.gz` to the release. For the release notes, use
|
|
the CHANGELOG.md entry plus the following template:
|
|
|
|
--------------------------------------------------------------------------------
|
|
|
|
**WORKSPACE setup**
|
|
|
|
```
|
|
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
|
|
http_archive(
|
|
name = "bazel_skylib",
|
|
urls = [
|
|
"https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz",
|
|
"https://github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz",
|
|
],
|
|
sha256 = "$SHA256SUM",
|
|
)
|
|
load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
|
|
bazel_skylib_workspace()
|
|
```
|
|
|
|
**Using the rules**
|
|
|
|
See [the source](https://github.com/bazelbuild/bazel-skylib/tree/$VERSION).
|
|
|
|
-------------------------------------------------------------------------------- |