examples: pin bsr-quickstart to one buffa release and check it in CI

.changes/unreleased/fixed-20260909-125500.yaml

@@ -0,0 +1,4 @@
+kind: Fixed
+body: |-
+    **`examples/bsr-quickstart` builds again** (#427). Its checked-in generated code had been hand-patched since it was generated from the v0.5.2 plugin, so it matched neither that plugin nor the current runtime. It is now regenerated from the `buf.build/anthropics/buffa:v0.9.2` plugin and depends on `buffa` / `buffa-types` 0.9.2 from crates.io, and CI builds it.
+time: 2026-09-09T12:55:00.000000000-07:00

.github/workflows/ci.yml

@@ -93,6 +93,15 @@ jobs:
       - name: Shared descriptor pool compile
         run: cargo test -p buffa-codegen --test shared_pool_compile -- --ignored
 
+      # `examples/bsr-quickstart` is outside the workspace, and its `src/gen/`
+      # is checked-in output from the published BSR plugin, not in-tree
+      # codegen. Its runtime deps are pinned to the plugin's release (see its
+      # `Cargo.toml`), so this fails if the pins diverge or `src/gen/` is
+      # hand-edited. `--locked` keeps new upstream releases of its transitive
+      # deps from changing the result. (#427)
+      - name: Check bsr-quickstart example
+        run: cargo check --locked --manifest-path examples/bsr-quickstart/Cargo.toml
+
   # ── Markdown lint ────────────────────────────────────────────────────────
   # Same pinned markdownlint-cli version as `task lint-md`. Node is
   # preinstalled on ubuntu-latest so no setup-node step is needed.

CONTRIBUTING.md

@@ -134,6 +134,8 @@ Three sets of generated code are checked into the repo and **must be regenerated
 
 3. **Logging example** (`examples/logging/src/gen/`): Regenerate with `task gen-logging-example` (requires `buf` on PATH).
 
+The `bsr-quickstart` example's `examples/bsr-quickstart/src/gen/` is the exception: it holds output from the *published* BSR plugin, so codegen changes do not regenerate it. Once the `buf.build/anthropics/buffa` plugin for a new release is published, bump the plugin pin in its `buf.gen.yaml` and the `buffa` / `buffa-types` versions in its `Cargo.toml` together, then run `task gen-bsr-quickstart-example`.
+
 CI (`check-generated-code` job) will fail if checked-in generated code is stale.
 
 ## Cross-Target Checks

Taskfile.yml

@@ -667,17 +667,19 @@ tasks:
       consumer-facing remote-plugin workflow, so it deliberately uses
       the published plugin rather than the in-tree `protoc-gen-buffa`.
       The plugin version is pinned in `buf.gen.yaml` for reproducible
-      output — bump the pin and re-run this task when a new BSR plugin
-      release ships, not after every codegen change. `src/gen/mod.rs` is
-      hand-written and not touched by buf.
+      output, and the example's `Cargo.toml` pins `buffa` / `buffa-types`
+      to the same release. When a new BSR plugin release ships, bump all
+      three together and re-run this task — not after every codegen
+      change. `src/gen/mod.rs` is hand-written and not touched by buf.
     dir: examples/bsr-quickstart
     cmds:
       - rm -f src/gen/example.v1.rs
       - buf generate
 
   # The examples are independent cargo projects (own Cargo.toml, own target/),
-  # not workspace members — they declare path deps on the workspace crates to
-  # mirror a downstream consumer's setup.
+  # not workspace members. Most declare path deps on the workspace crates to
+  # mirror a downstream consumer's setup; bsr-quickstart instead depends on the
+  # crates.io release matching its BSR plugin pin.
 
   build-examples:
     desc: Build all example binaries.

examples/bsr-quickstart/Cargo.toml

@@ -10,18 +10,12 @@ plugin with `file_per_package=true` and a hand-written `mod.rs`. See
 """
 
 [dependencies]
-# Path dependencies so the example builds against the in-tree workspace
-# (consistent with the other `examples/*`). The checked-in `src/gen/` is
-# generated by the *published* BSR plugin pinned in `buf.gen.yaml`, so this
-# example also acts as a forward-compat canary: if an in-tree runtime change
-# ever breaks code generated by the published plugin, this example fails to
-# build. In a real downstream project, use crates.io versions instead:
-#   buffa       = { version = "0.9", features = ["json"] }
-#   buffa-types = { version = "0.9", features = ["json"] }
-#   serde       = { version = "1", features = ["derive"] }
-#   serde_json  = "1"
-buffa = { path = "../../buffa", features = ["json"] }
-buffa-types = { path = "../../buffa-types", features = ["json"] }
+# crates.io releases, not path dependencies: `src/gen/` is output from the
+# published plugin pinned in `buf.gen.yaml`, which trails `main`, so it only
+# compiles against the runtime from that same release. Keep these versions
+# equal to that pin. In your own project, `version = "0.9"` is enough.
+buffa = { version = "=0.9.2", features = ["json"] }
+buffa-types = { version = "=0.9.2", features = ["json"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 

examples/bsr-quickstart/buf.gen.yaml

@@ -9,13 +9,13 @@
 # `protoc-gen-buffa-packaging` locally and add it as a second plugin (and
 # drop `file_per_package=true`).
 #
-# The plugin reference is pinned to a specific version so the generated
-# output is reproducible and a plugin update can't silently change it. Match
-# the pin to the `buffa` runtime crate version in `Cargo.toml`. Bump it (and
-# `task gen-bsr-quickstart-example`) when a new BSR plugin release ships.
+# The plugin reference is pinned so the generated output is reproducible and a
+# plugin update can't silently change it. `Cargo.toml` pins `buffa` /
+# `buffa-types` to the same release: bump all three together, then run
+# `task gen-bsr-quickstart-example`.
 version: v2
 plugins:
-  - remote: buf.build/anthropics/buffa:v0.5.2
+  - remote: buf.build/anthropics/buffa:v0.9.2
     out: src/gen
     opt:
       - file_per_package=true