BCR PR Review Style Guide (for Gemini Code Assistant)

Gemini Code Assistant acting as a reviewer-helper for PRs to the Bazel Central Registry (BCR).

Goals: Ensure PRs follow BCR policies, stay “add‑only,” are secure, reproducible, and easy for downstream users.

0) TL;DR – One‑Screen Checklist

Gatekeepers (block PR if any fail):

  • [ ] Add‑only: PR doesn’t mutate existing module versions or non‑module files when adding a version.
  • [ ] Required files present and valid: modules/<name>/metadata.json, modules/<name>/<version>/{MODULE.bazel, source.json, presubmit.yml}.
  • [ ] Maintainers listed: metadata.json.maintainers includes at least one GitHub handle.

Strong suggestions (ask for changes, but not always blockers):

  • [ ] Module name is specific and unambiguous (avoid overly generic names).
  • [ ] For C++ overlays: ensure a public target named after the module (or alias libfoo -> foo); visibility is minimal but includes //visibility:public for intended APIs.
  • [ ] If using overlays: include bazel_compatibility >= 7.2.1 and brief notes on how large BUILD overlays were created.
  • [ ] Prefer adding a test module and/or anonymous module verify targets;
  • [ ] Encourage to build everything from source (no prebuilt binaries) unless absolutely necessary. Registering prebuilt toolchains is a common and acceptable exception.

1) What “Good” Looks Like

Structure

modules/
  <module_name>/
    metadata.json
    <version>/
      MODULE.bazel
      source.json
      presubmit.yml
      # optional:
      patches/*.patch
      overlays/**/*
      README.md (e.g., document BUILD overlays)

Versioning

  • BCR is add-only: never mutate an existing published version. To fix issues found only in BCR patches, add a new version with a .bcr.N suffix.
  • Pseudo-versions allowed (e.g. 1.19.1-YYYYMMDDHHMMSS-abcdef) when upstream is stale.

Source

  • You can ignore reviewing the source.json file as it will be tested in presubmit.

Presubmit & Validations

  • presubmit.yml is required for each version. Anonymous-module tasks should be put under the top-level tasks key, and test-module tasks under bcr_test_module.tasks. tasks should not be specified anywhere else because they will be ignored.
  • Each task must specify at least one of build_targets or test_targets, but not necessarily both.

Metadata

  • metadata.json.maintainers includes github and ideally github_user_id; optional fields are fine (name, email, website, do_not_notify).
  • Gemini should ping @bazelbuild/bcr-maintainers for a manual review if there are any significant changes (ignoring reformatting) to the maintainers or repository fields in metadata.json files.

MODULE.bazel

  • The MODULE.bazel file may contain overrides (e.g. archive_override, git_override, local_path_override). Those will be ignored when the module is used as a dependency, so they are allowed and you can ignore reviewing them.
  • The MODULE.bazel file may contain dev dependencies specified with dev_dependency = True. Dev dependencies are ignored when the module is used as a dependency, so they are allowed and you can ignore reviewing them.
  • There could be symlinks under overlay/ directory that points to a MODULE.bazel file in the parent directory. The content of the symlink will look like a text file ../MODULE.bazel, these are allowed and should be ignored.
  • Bazel module resolution allows cyclic dependencies.

2) Handy References & Commands (for authors)

  • Validate locally: bazel run -- //tools:bcr_validation --check=<name>@<version>

  • Update integrity: bazel run -- //tools:update_integrity <name>

  • Reproduce presubmit repos: bazel run -- //tools:setup_presubmit_repos --module @<name>

  • Test with local registry:

    bazel shutdown && bazel build --enable_bzlmod \
  --registry="file:///path/to/bazel-central-registry" \
  --lockfile_mode=off @<module>//:<target>