Update README and example docs

README.md

@@ -8,47 +8,69 @@ 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.
+### 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`:
+
+```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.68.4")
+
+use_repo(buf, "rules_buf_toolchains")
+```
+
+### Legacy `WORKSPACE`
+
+For projects that have not yet migrated to Bazel modules:
 
 ```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",
     ],
 )
 
 load("@rules_buf//buf:repositories.bzl", "rules_buf_dependencies", "rules_buf_toolchains")
 
 rules_buf_dependencies()
 
-rules_buf_toolchains(version = "v1.32.1")
+rules_buf_toolchains(version = "v1.68.4")
 
 # 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.

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)
+### [Bazel Modules](bzlmod)
 
-This demonstrates using this repo with [bzlmod](https://docs.bazel.build/versions/5.0.0/bzlmod.html).
+This demonstrates using this repo with [Bazel modules](https://bazel.build/versions/9.1.0/external/overview).
 
 ### [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`](https://buf.build/docs/configuration/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`.

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

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.