docs/maintainers_guide.md

# 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 compatibility 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, MODULE.bazel, *and* gazelle/MODULE.bazel to
    the new version.
    TODO(#386): add a test to make sure all the versions are in sync.
3.  Ensure that the commits for steps 1 and 2 have been merged.
4.  Create a new tag in the format `1.2.3` (no leading `v`) and push it to
    GitHub.
5.  Review a PR at [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry)
    created by the publish.yaml workflow.
6.  Download the the `bazel-skylib-$VERSION.tar.gz` and
    `bazel-skylib-gazelle-plugin-$VERSION.tar.gz` tarballs from the
    automatically created GitHub release and upload them to the mirror (you'll
    need Bazel developer gcloud credentials; assuming you are a Bazel developer,
    you can obtain them via `gcloud init`):

```bash
gsutil cp bazel-skylib{,-gazelle-plugin}-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/
gsutil 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
```