Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 39 ยท Testing and Versioning

Buf: Linting and Breaking-Change Detection

Use the buf CLI to lint protobuf files, detect breaking changes against main, generate code and run it in CI, with runnable Go examples of lint and breaking-change rules.

The rules in schema evolution are easy to state and easy to forget at 5 p.m. on a Friday. A reviewer who sees - int32 age = 2; and + string nickname = 2; has to know that this is dangerous. Better to let a tool check every change. The standard tool is buf, a fast protobuf toolchain that replaces most uses of protoc: it lints, detects breaking changes, formats and generates code, all driven by one config file.

The buf binary cannot run on this site, so commands and config are shown read-only. The runnable blocks implement two real rules (naming lint and breaking-change detection) over a tiny schema model, so you see exactly the kind of checks buf performs.

Project layout

TEXT
proto/
  buf.yaml
  users/v1/users.proto
  orders/v1/orders.proto
buf.gen.yaml

buf.yaml declares the module and rules:

YAML
version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
  except:
    - PACKAGE_VERSION_SUFFIX   # example of relaxing one rule
breaking:
  use:
    - FILE

Common commands:

Terminal
buf lint                         # style and best-practice checks
buf format -w                    # canonical formatting, in place
buf breaking --against '.git#branch=main'   # compare with the main branch
buf generate                     # run code generators from buf.gen.yaml
buf build                        # compile, fail on errors

Linting

buf lint enforces the Google/Buf style guide. The default STANDARD rule set includes, among others:

Rule What it wants
PACKAGE_VERSION_SUFFIX Package ends with a version: users.v1
SERVICE_SUFFIX Service names end with Service: UserService
RPC_REQUEST_STANDARD_NAME Request is <Rpc>Request (GetUserRequest)
RPC_RESPONSE_STANDARD_NAME Response is <Rpc>Response or the resource
MESSAGE_PASCAL_CASE UserProfile
FIELD_LOWER_SNAKE_CASE display_name
ENUM_VALUE_UPPER_SNAKE_CASE STATUS_ACTIVE
ENUM_VALUE_PREFIX Enum values start with the enum name: STATUS_ACTIVE
ENUM_ZERO_VALUE_SUFFIX The zero value ends in _UNSPECIFIED
PACKAGE_DIRECTORY_MATCH users.v1 lives in users/v1/

Consistent names mean consistent generated code in every language, and the Request/Response convention leaves room for adding fields later without changing the method signature.

Go A mini linter for protobuf names

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Breaking-change detection

buf breaking compares the current files with a previous version (a git branch, a tag, a directory or the Buf Schema Registry) and reports every change that could hurt clients. You choose a strictness category by how much compatibility you promise:

  • FILE: the strictest. Source code compatibility of generated code in all languages (for example, moving a message to another file breaks).
  • PACKAGE: like FILE but tolerant of moving things between files in the same package.
  • WIRE_JSON: only what breaks binary and JSON encodings (for example renaming a field breaks JSON, since JSON uses names).
  • WIRE: only what breaks the binary wire format.

Typical rule names: FIELD_NO_DELETE, FIELD_SAME_TYPE, FIELD_SAME_NAME, MESSAGE_NO_DELETE, ENUM_VALUE_NO_DELETE, RPC_NO_DELETE, RPC_SAME_REQUEST_TYPE, RESERVED_ENUM_NO_DELETE. Pick FILE for libraries that other teams compile, and WIRE_JSON when only data compatibility matters.

Go A mini breaking-change detector

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The detector complains about the type change on field 2, the rename of field 3 and the deleted Order message, but not about the new field 4. That matches real buf breaking behaviour.

Generating code

buf.gen.yaml lists plugins; buf generate runs them all, with pinned versions, so every developer and CI job produces the same files:

YAML
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/grpc/go
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/grpc-ecosystem/gateway
    out: gen/go
  - remote: buf.build/grpc-ecosystem/openapiv2
    out: gen/openapi

Commit the generated code, or generate in CI and publish packages, whichever suits your team; just never edit generated files by hand.

In CI

A minimal GitHub Actions job runs the whole chain on every pull request:

YAML
name: proto
on: pull_request
jobs:
  buf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bufbuild/buf-setup-action@v1
      - uses: bufbuild/buf-lint-action@v1
      - uses: bufbuild/buf-breaking-action@v1
        with:
          against: 'https://github.com/acme/api.git#branch=main'

For larger organizations the Buf Schema Registry hosts modules, generates SDKs on demand and runs breaking checks against published versions, so consumers depend on a version, not a copy of the files.

Practical rules

  • Run buf lint and buf breaking in CI; make failures block merging.
  • If a break is intentional, ship it as a new version (v2), not by silencing the check.
  • Put annotations like google.api.http under the same checks as the rest.
  • Keep one source of truth for protos: do not copy files between repositories.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does buf breaking --against '.git#branch=main' do?

    It checks the current schema against a baseline and fails when a change could break existing clients.
  2. 2. Which breaking category only cares about binary wire compatibility?

    WIRE is the loosest: it flags only changes that break the binary encoding. WIRE_JSON also covers JSON names.
  3. 3. Which standard lint rule requires the zero enum value to end in _UNSPECIFIED?

    ENUM_ZERO_VALUE_SUFFIX enforces the convention that default enum values mean unspecified.
  4. 4. What should you do when a breaking change is truly needed?

    A new version lets old clients keep using v1 while new clients move to v2.

Summary

  • buf lints, formats, builds, generates code and checks breaking changes from one buf.yaml.
  • The standard lint rules enforce naming conventions (Service suffix, XRequest names, _UNSPECIFIED zero values, versioned packages).
  • buf breaking compares against a baseline using the FILE, PACKAGE, WIRE_JSON or WIRE strictness level.
  • Run lint and breaking checks on every pull request and block merges on failures.
  • Real breaks go into a new API version, not past a silenced check.

Next: Load Testing and Performance Tuning