| name | buf-version-pinning |
| description | Use when editing `buf.yaml`, `buf.lock`, or any `buf.gen.yaml` (root, server, or SDK). Generator plugin versions in `buf.gen.yaml` are tightly coupled to the generated code consumers (Connect-RPC client, sqlc, SDK shapes); a version bump can produce a large unrelated diff and break downstream code that relies on specific output shapes. |
buf-version-pinning
buf.gen.yaml declares which protoc plugins (and which versions) generate
the Go, TypeScript, and Python output. Bumping a plugin version regenerates
every file the plugin produces, even for protos that didn't change. This
is normal but easy to confuse with bugs.
What to do
- When the diff is a
buf.gen.yaml plugin version bump, expect a wide
regen sweep — surface that to the user before they assume the diff is
wrong.
- After the change, run
just gen and group the diff by language so the
user can see scope at a glance.
- If
buf.lock changed, confirm buf.yaml deps changed correspondingly
(or that buf dep update was run intentionally).
- Check whether any consumers of the generated output rely on a specific
plugin version (e.g. a Connect generator API change) before merging.
What to avoid
- Don't pin a plugin version to "make the diff smaller". The repo prefers
current pinned versions across all
buf.gen.yaml files.
- Don't hand-edit
buf.lock.
