check the declarations with buf lint and buf breaking - #76
Open
hugowetterberg wants to merge 1 commit into
Open
Conversation
The seven declarations here predate buf's conventions and violate the STANDARD rules in twenty-nine places across nine rules. Every one of them is breaking to fix: a package name and a service name are both in the Connect procedure path and the Twirp path, a message name is in the generated Go that every consumer in the fleet compiles against, and a field name is what Twirp's JSON emits. So nothing is renamed. buf.yaml turns the rules on with no "except" list and grandfathers the existing files one rule at a time, which means a rule applies to every file that is not listed and a new declaration gets the full set. The block was generated by "buf lint --error-format=config-ignore-yaml" rather than written by hand, and it only ever shrinks. Breaking changes are checked at FILE rather than WIRE_JSON, because this repository's deliverable is generated Go: renaming a message is wire-compatible and still breaks every consumer that compiles against the package. The CI job runs the lint, then a generation drift check, then the breaking check. The drift check is new and is the gap worth closing on its own — nothing in CI regenerated anything, so a hand-edited service.pb.go went unnoticed. It is ordered before the breaking check because a stale generated tree makes that result untrustworthy, and the checkout is unshallowed because buf compares against the tip of main. The declarations are not reformatted. All seven fail "buf format", a diff of some two thousand lines, and that belongs in a change of its own where the regenerated output can be seen to be unaffected.
hugowetterberg
force-pushed
the
feature/buf-lint
branch
from
September 10, 2026 08:49
8b54102 to
58d8c8b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Turns buf's lint and breaking-change rules on for this repository's declarations, without changing a single one of them.
The seven declarations here predate buf's conventions and violate the STANDARD rules in twenty-nine places across nine rules. Every one of them is breaking to fix: a package name and a service name are both in the Connect procedure path and the Twirp path, a message name is in the generated Go that every consumer in the fleet compiles against, and a field name is what Twirp's JSON emits. So nothing is renamed.
buf.yamlturns the rules on with noexceptlist and grandfathers the existing files one rule at a time, which means a rule applies to every file that is not listed and a new declaration gets the full set. The block was generated bybuf lint --error-format=config-ignore-yamlrather than written by hand, and it only ever shrinks — entries are removed when a file is brought into line, never added.Breaking changes are checked at
FILErather thanWIRE_JSON, because this repository's deliverable is generated Go: renaming a message is wire-compatible and still breaks every consumer that compiles against the package.The CI job
Three steps, in the order that makes them trustworthy: lint first because it is cheapest and its failures are the most local; then a generation drift check; then the breaking check, last because a stale generated tree would make its result meaningless. The checkout is unshallowed because buf compares against the tip of
main.The drift check is new and is worth having on its own. Nothing in CI regenerated anything before this, so a hand-edited
service.pb.gowould have gone unnoticed.Depends on ttab/mage#18
go.modpinsgithub.com/ttab/mageat a pseudo-version of that pull request's head, sincerpc:lintandrpc:breakingdo not exist in a released version yet. Re-pin to a releasedttab/magebefore merging, and re-runmage rpc:generateafterwards to confirm no drift — a mage bump can move the pinned generator versions as well as add targets.The module-root change in that pull request does not affect this repository: the proto root here is the repository root, so no
buf.yamlis generated, the hand-written one is left alone, and generation is byte-identical. Verified on this branch.Not included
All seven declarations fail
buf format --exit-code— a diff of some two thousand lines, dominated by buf movingimportbelowpackageand unwinding aligned=columns. That belongs in a change of its own, where the regenerated output can be seen to be unaffected.