From 67624e6b1e5927415146d28098b4ed0712a27f85 Mon Sep 17 00:00:00 2001 From: "Philip K. Warren" Date: Mon, 27 Apr 2026 14:35:51 -0500 Subject: [PATCH 1/2] Update README and example docs Update the README to use more recent examples, fix some links, and mention the format rule. --- README.md | 54 ++++++++++++++++++++++---------- examples/README.md | 22 +++++++++++-- examples/single_module/README.md | 4 +-- examples/v2/README.md | 11 ++++--- 4 files changed, 65 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 5e45a21..2e056cb 100644 --- a/README.md +++ b/README.md @@ -8,17 +8,34 @@ This module is a beta, but we may make a few changes as we gather feedback from ## Setup -Include the following snippet in the Workspace file to setup `rules_buf`. Refer to [release notes](https://github.com/bufbuild/rules_buf/releases) of a specific version for setup instructions. +### Bzlmod (`MODULE.bazel`) + +`rules_buf` is published to the [Bazel Central Registry](https://registry.bazel.build/modules/rules_buf). Add the following to your `MODULE.bazel`: + +```starlark +bazel_dep(name = "rules_buf", version = "0.5.2") + +buf = use_extension("@rules_buf//buf:extensions.bzl", "buf") + +# Pin the buf CLI version (optional; a default version is used otherwise). +buf.toolchains(version = "v1.47.2") + +use_repo(buf, "rules_buf_toolchains") +``` + +### Legacy `WORKSPACE` + +For projects that have not yet migrated to Bzlmod: ```starlark load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "rules_buf", - integrity = "sha256-Hr64Q/CaYr0E3ptAjEOgdZd1yc+cBjp7OG1wzuf3DIs=", - strip_prefix = "rules_buf-0.3.0", + sha256 = "4a024a411996967c3a3f49b04765bd016169a2c79be3dc78aa62bfa2643850ef", + strip_prefix = "rules_buf-0.5.2", urls = [ - "https://github.com/bufbuild/rules_buf/archive/refs/tags/v0.3.0.zip", + "https://github.com/bufbuild/rules_buf/releases/download/v0.5.2/rules_buf-0.5.2.tar.gz", ], ) @@ -26,29 +43,34 @@ load("@rules_buf//buf:repositories.bzl", "rules_buf_dependencies", "rules_buf_to rules_buf_dependencies() -rules_buf_toolchains(version = "v1.32.1") +rules_buf_toolchains(version = "v1.47.2") # rules_proto -load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies", "rules_proto_toolchains") +load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies") rules_proto_dependencies() -rules_proto_toolchains() +load("@rules_proto//proto:setup.bzl", "rules_proto_setup") + +rules_proto_setup() ``` -Refer the [docs](https://docs.buf.build/build-systems/bazel) or browse the [examples](examples) on how to setup and use for various scenarios. +Refer to the latest [release notes](https://github.com/bufbuild/rules_buf/releases) for the exact `sha256` and version to pin. + +Refer to the [docs](https://buf.build/docs/cli/build-systems/bazel) or browse the [examples](examples) on how to set up and use `rules_buf` in various scenarios. ## List of rules -- [buf_dependencies](https://docs.buf.build/build-systems/bazel#buf-dependencies) -- [buf_lint_test](https://docs.buf.build/build-systems/bazel#buf-lint-test) -- [buf_breaking_test](https://docs.buf.build/build-systems/bazel#buf-breaking-test) +- [buf_dependencies](https://buf.build/docs/cli/build-systems/bazel#buf-dependencies) +- [buf_lint_test](https://buf.build/docs/cli/build-systems/bazel#buf-lint-test) +- [buf_breaking_test](https://buf.build/docs/cli/build-systems/bazel#buf-breaking-test) +- [buf_format](https://buf.build/docs/cli/build-systems/bazel#buf-format) ## Gazelle Extension The repo also offers a Gazelle extension for generating the rules. -Please refer to the [gazelle section](https://docs.buf.build/build-systems/bazel#gazelle) in the docs. +Please refer to the [gazelle section](https://buf.build/docs/cli/build-systems/bazel#gazelle) in the docs. ## Development @@ -60,10 +82,10 @@ All the rule definitions are in [buf/internal](buf/internal). Gazelle extension is in [gazelle/buf](gazelle/buf). Before looking at the code it would be best to understand the [architecture of gazelle](https://github.com/bazelbuild/bazel-gazelle/blob/master/Design.rst). The file structure is loosely based on the `go` and `proto` [extensions](https://github.com/bazelbuild/bazel-gazelle/tree/master/language) that are shipped with gazelle. They are also excellent to better understand the architecture. -The main entry point to the extension is via the `NewLanguage` function in [gazelle/buf/buf.go](gazelle/buf/buf.go). Gazelle mostly depends on [`Language`](https://pkg.go.dev/github.com/bazelbuild/bazel-gazelle@v0.25.0/language#Language) interface. Apart from that one can also implement some optional interfaces. +The main entry point to the extension is via the `NewLanguage` function in [gazelle/buf/buf.go](gazelle/buf/buf.go). Gazelle mostly depends on [`Language`](https://pkg.go.dev/github.com/bazelbuild/bazel-gazelle@v0.34.0/language#Language) interface. Apart from that one can also implement some optional interfaces. We implement the following interfaces, -- [`Language`](https://pkg.go.dev/github.com/bazelbuild/bazel-gazelle@v0.25.0/language#Language): Required. Used for build/test rule generation and label resolutions for these rules. -- [`RepoImporter`](https://pkg.go.dev/github.com/bazelbuild/bazel-gazelle@v0.25.0/language#RepoImporter): Optional. Used to generate `buf_dependencies` rule from `buf.yaml`/`buf.work.yaml`. -- [`CrossResolver`](https://pkg.go.dev/github.com/bazelbuild/bazel-gazelle@v0.25.0/resolve#CrossResolver): Optional. Used to resolve dependencies across extensions/languages. We use it to resolve any proto files that are part of `buf_dependencies` rules. +- [`Language`](https://pkg.go.dev/github.com/bazelbuild/bazel-gazelle@v0.34.0/language#Language): Required. Used for build/test rule generation and label resolutions for these rules. +- [`RepoImporter`](https://pkg.go.dev/github.com/bazelbuild/bazel-gazelle@v0.34.0/language#RepoImporter): Optional. Used to generate `buf_dependencies` rule from `buf.yaml`/`buf.work.yaml`. +- [`CrossResolver`](https://pkg.go.dev/github.com/bazelbuild/bazel-gazelle@v0.34.0/resolve#CrossResolver): Optional. Used to resolve dependencies across extensions/languages. We use it to resolve any proto files that are part of `buf_dependencies` rules. diff --git a/examples/README.md b/examples/README.md index e6df61a..8b53c5a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,12 +1,12 @@ # Examples -Examples on how to use `rules_buf` in various scenarios. For more info refer to the [official docs](https://docs.buf.build/build-systems/bazel). +Examples on how to use `rules_buf` in various scenarios. For more info refer to the [official docs](https://buf.build/docs/cli/build-systems/bazel). ## Scenarios ### [bzlmod](bzlmod) -This demonstrates using this repo with [bzlmod](https://docs.bazel.build/versions/5.0.0/bzlmod.html). +This demonstrates using this repo with [Bzlmod](https://bazel.build/external/overview#bzlmod). ### [Version](version) @@ -22,4 +22,20 @@ This demonstrates setting up lint and breaking tests in a project with a `buf.ya ### [Workspaces](workspace) -This demonstrates setting up lint and breaking tests in a [buf workspace](https://docs.buf.build/reference/workspaces) project. +This demonstrates setting up lint and breaking tests in a v1 `buf.work.yaml` workspace project. + +### [v2](v2) + +This demonstrates setting up lint and breaking tests using a [v2 `buf.yaml`](https://buf.build/docs/configuration/v2/buf-yaml) workspace. + +### [Echo](echo) + +A minimal end-to-end example: `proto_library` plus generated Connect/Go server code, built and run via Bazel. + +### [Toolchain](toolchain) + +This demonstrates using the `buf_format` rule together with the [`toolchains_protoc`](https://github.com/aspect-build/toolchains_protoc) hermetic `protoc` toolchain. + +### [Unused](unused) + +This exercises the lint extension's behavior on a `proto_library` that includes an unused import, using the standard `protobuf` Bazel module for `protoc`. diff --git a/examples/single_module/README.md b/examples/single_module/README.md index e9034fb..8ddd509 100644 --- a/examples/single_module/README.md +++ b/examples/single_module/README.md @@ -3,13 +3,13 @@ The example uses lint and breaking rules with a single module `buf.yaml`. - The `buf.yaml` is exported in [BUILD](BUILD.bazel) -- [foo/v1](foo/v1/BUILD.bazel) contains lint rule that succeeds, it can be exeucted using +- [foo/v1](foo/v1/BUILD.bazel) contains lint rule that succeeds, it can be executed using ```sh bazel test //foo/v1:foo_proto_lint ``` -- [bar/v1](bar/v1/BUILD.bazel) contains lint rule that fails, it can be exeucted using +- [bar/v1](bar/v1/BUILD.bazel) contains lint rule that fails, it can be executed using ```sh bazel test //bar/v1:bar_proto_lint diff --git a/examples/v2/README.md b/examples/v2/README.md index 501adfd..ab13a34 100644 --- a/examples/v2/README.md +++ b/examples/v2/README.md @@ -1,8 +1,9 @@ -# Workspace +# v2 `buf.yaml` workspace -This example demonstrates how to uses `rules_buf` with [workspaces](https://docs.buf.build/reference/workspaces). +This example demonstrates using `rules_buf` with a [v2 `buf.yaml`](https://buf.build/docs/configuration/v2/buf-yaml) workspace. A single root `buf.yaml` declares the workspace's modules under `modules:` and applies shared `lint` and `breaking` configuration across all of them. -- Export each `buf.yaml` ([fooapis](fooapis/BUILD.bazel#L4), [barapis](barapis/BUILD.bazel#L4)) -- `proto_library` rules need an additional argument `strip_import_prefix` ([foo/v1](fooapis/foo/v1/BUILD.bazel#L7), [bar/v1](barapis/bar/v1/BUILD.bazel#L7)) +- The root `buf.yaml` is exported in [BUILD](BUILD). +- Each `buf_lint_test` and `buf_breaking_test` references the root `buf.yaml` via `config = "//:buf.yaml"` and identifies its module with the `module` attribute (e.g. `module = "fooapis"`). +- `proto_library` rules use `strip_import_prefix` so that imports resolve relative to the module root ([fooapis/foo/v1](fooapis/foo/v1/BUILD.bazel), [barapis/bar/v1](barapis/bar/v1/BUILD.bazel)). -Checkout the [gazelle example](../gazelle) for way to generate the rules. +See the [Gazelle example](../gazelle) for how to generate these rules automatically. From b6e493d13f248735f4e1256530f3393a8a63210f Mon Sep 17 00:00:00 2001 From: "Philip K. Warren" Date: Mon, 27 Apr 2026 14:53:50 -0500 Subject: [PATCH 2/2] Address review comments --- README.md | 8 ++++---- examples/README.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 2e056cb..93b5004 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This module is a beta, but we may make a few changes as we gather feedback from ## Setup -### Bzlmod (`MODULE.bazel`) +### Bazel modules (`MODULE.bazel`) `rules_buf` is published to the [Bazel Central Registry](https://registry.bazel.build/modules/rules_buf). Add the following to your `MODULE.bazel`: @@ -18,14 +18,14 @@ bazel_dep(name = "rules_buf", version = "0.5.2") buf = use_extension("@rules_buf//buf:extensions.bzl", "buf") # Pin the buf CLI version (optional; a default version is used otherwise). -buf.toolchains(version = "v1.47.2") +buf.toolchains(version = "v1.68.4") use_repo(buf, "rules_buf_toolchains") ``` ### Legacy `WORKSPACE` -For projects that have not yet migrated to Bzlmod: +For projects that have not yet migrated to Bazel modules: ```starlark load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") @@ -43,7 +43,7 @@ load("@rules_buf//buf:repositories.bzl", "rules_buf_dependencies", "rules_buf_to rules_buf_dependencies() -rules_buf_toolchains(version = "v1.47.2") +rules_buf_toolchains(version = "v1.68.4") # rules_proto load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies") diff --git a/examples/README.md b/examples/README.md index 8b53c5a..183695a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,9 +4,9 @@ Examples on how to use `rules_buf` in various scenarios. For more info refer to ## Scenarios -### [bzlmod](bzlmod) +### [Bazel Modules](bzlmod) -This demonstrates using this repo with [Bzlmod](https://bazel.build/external/overview#bzlmod). +This demonstrates using this repo with [Bazel modules](https://bazel.build/versions/9.1.0/external/overview). ### [Version](version) @@ -22,7 +22,7 @@ This demonstrates setting up lint and breaking tests in a project with a `buf.ya ### [Workspaces](workspace) -This demonstrates setting up lint and breaking tests in a v1 `buf.work.yaml` workspace project. +This demonstrates setting up lint and breaking tests in a [v1 `buf.work.yaml`](https://buf.build/docs/configuration/v1/buf-work-yaml/) workspace project. ### [v2](v2)