buf v2 config - #859
Conversation
Preparation for migrating buf.yaml to v2. The pinned v1.27.0 predates v2 config and rejects it outright, so it has to move first. v1.49.0 is what .github/workflows/push-to-buf.yml already runs against this repo. v1.32.0 moved buf mod prune to buf dep prune and deprecated the old spelling, so the Makefile target follows. Any buf that new also prunes buf.build/grpc-ecosystem/grpc-gateway out of buf.lock, because nothing under temporal/ imports it. Left in buf.yaml, that prune would dirty the tree and fail CI's uncommitted-changes check, so drop the dep and commit the pruned lock.
Autogenerated, no hand edits:
buf config migrate --module .
buf's own migration path, per
https://buf.build/docs/migration-guides/migrate-v2-config-files/. --module
restricts it to buf.yaml and buf.lock, leaving buf.gen.yaml at v1; that file is
unreferenced by the Makefile and CI and points at a protoc-gen-go-helpers
directory that does not exist here, so it is dead config and out of scope.
v2 exists since v1.32.0. v1 remains supported with no deadline, so this is not
a forced upgrade; the motivation is that the buf language server does not
discover module roots from a v1 buf.yaml, and reports every import in every
.proto as unresolved.
The added lint and breaking except entries are the tool preserving current
behaviour: v2 turns on rules that v1 did not run.
Two hand fixups on top of the generated migration. buf config migrate rewrites buf.yaml structurally and drops comments. The two comments on excludes are replaced by one line stating why they are needed, both halves of which are verified: dropping either exclude makes buf build fail with "contained in multiple modules", and moving either vendored directory aside makes api-linter fail to resolve its imports, since it reads -I paths and not the BSR. v1.40.0 renamed the DEFAULT lint category to STANDARD and buf warns on every invocation while the old name is used. buf config ls-lint-rules on each expands to the same 36 rules, so this is a rename only. The tool does not do it because DEFAULT still works.
There was a problem hiding this comment.
Pull request overview
Migrates Buf module configuration to v2 and updates the pinned Buf CLI.
Changes:
- Migrates module, lint, breaking-change, and lockfile configuration to v2.
- Updates Buf to v1.49.0 and adopts
buf dep prune. - Removes an unused dependency and the generation template.
Reviewed changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
Makefile |
Updates Buf installation and dependency pruning. |
buf.yaml |
Migrates module configuration to v2. |
buf.lock |
Migrates dependency locks to v2. |
buf.gen.yaml |
Deletes the Buf generation template. |
Suppressed comments (1)
buf.gen.yaml:1
- Deleting the repository’s generation template removes the configuration discovered by
buf generate; that command will now fail unless every caller supplies an external template. Preserve this file (migrating it to v2 if desired), or add an equivalent replacement rather than removing generation support as part of the module-config migration.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| - nexusannotations | ||
| deps: | ||
| - buf.build/grpc-ecosystem/grpc-gateway |
There was a problem hiding this comment.
I guess we never used this?
| - FIELD_NOT_REQUIRED | ||
| - PACKAGE_NO_IMPORT_CYCLE |
There was a problem hiding this comment.
Are these precautionary exclusions or would these actually break the lint today?
There was a problem hiding this comment.
Thanks. They were added automatically by buf config migrate --module . in d81350b, but I've removed them now.
stephanos
left a comment
stephanos
left a comment
There was a problem hiding this comment.
LGTM with limited buf knowledge. Fact that behavior seems the same is good.
| - DEFAULT | ||
| - WIRE_JSON | ||
| except: | ||
| - FIELD_SAME_DEFAULT |
There was a problem hiding this comment.
Could also check if this is needed.
|
I’m missing context, and don’t know much about But it indeed looks like we’re only using As for the version bump and config change, the worst case would be developer frictions (our devs, not external) if the new version/config results in different stylistic/linting recommendations. I assume you did exercise all the make commands and CI jobs that use So LGTM. |
What changed?
Migrated
buf.yamlandbuf.lockfrom config v1 to v2 usingbuf config migrate --module ..Bumped buf pinned in the Makefile from v1.27.0 to v1.49.0, and renamed
buf mod prunetobuf dep prune.Dropped the unused
buf.build/grpc-ecosystem/grpc-gatewaydependency.Renamed the lint category
DEFAULTtoSTANDARD, and replaced the two comments onexcludeswith one line.Deleted
buf.gen.yamlWhy?
LSP support: The buf language server does not discover module roots from a v1
buf.yaml.pin has to move because v1.27.0 predates v2 and rejects it. v1.49.0 is the version
.github/workflows/push-to-buf.ymlalready runs against this repo.DEFAULTwas renamed toSTANDARDin buf v1.40.0.AFAIK no-one calls
buf generate; we useprotocBreaking changes
Rerun
make buf-installto pick up the new buf. Otherwise none.