# Buf Version Pinning

> 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.

- Skill: `block/buf-version-pinning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add block/buf-version-pinning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/block/buf-version-pinning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: block (https://skillmd.com/u/block)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/block/buf-version-pinning

---


# 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

1. 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.
2. After the change, run `just gen` and group the diff by language so the
   user can see scope at a glance.
3. If `buf.lock` changed, confirm `buf.yaml` deps changed correspondingly
   (or that `buf dep update` was run intentionally).
4. 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`.