buf breaking-rule tables and worked evolution patterns

Full rule-ID tables for buf's four breaking categories, plus worked proto-evolution diffs. Sources: buf.build/docs/breaking/rules (opens in new window) and protobuf.dev/programming-guides/proto3/ (opens in new window).

FILE (default)

PACKAGE

WIRE_JSON

WIRE (most lenient)

Worked evolution patterns

Adding an optional field

Safe (always):

 message User {
   string name = 1;
+  string nickname = 2;
 }

Renaming a field

Add new, deprecate + reserve old:

 message User {
   string name = 1;
-  string nickname = 2;
+  string display_name = 3;
+  reserved 2;
+  reserved "nickname";
 }

Consumers must migrate from nickname to display_name. The wire format reads either; the codegen forces consumers to update.

Promoting int32 to int64

Wire-compatible per protobuf3 docs:

 message Counter {
-  int32 count = 1;
+  int64 count = 1;
 }

Old clients writing int32 still parse correctly. Old clients reading new int64 data truncate silently if the value exceeds int32 range.

Adding a field to a oneof

ALWAYS BREAKING. Don't.

 message Event {
   oneof body {
     string text = 1;
     bytes binary = 2;
+    string emoji = 3;  // BREAKS old parsers
   }
 }

Mitigation: add the new variant as a non-oneof field; promote later in a separate proto file/package.

buf CI integration

Gate buf build, buf lint, and buf breaking on every PR that touches .proto, buf.yaml, or buf.gen.yaml. All three must pass before merge.

GitHub Actions workflow

# .github/workflows/proto-gate.yml
name: proto-gate
on:
  pull_request:
    paths:
      - "**/*.proto"
      - "buf.yaml"
      - "buf.gen.yaml"

jobs:
  buf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0   # Required for `--against ".git#branch=main"`
      - uses: bufbuild/buf-setup-action@v1
        with:
          buf_user: ${{ secrets.BUF_USER }}
          buf_api_token: ${{ secrets.BUF_API_TOKEN }}
      - run: buf build
      - run: buf lint
      - run: buf breaking --against ".git#branch=main"

Key: fetch-depth: 0 so git has the baseline commit available. fetch-depth: 1 makes buf error because it cannot reach the baseline.

The official bufbuild/buf-setup-action and bufbuild/buf-breaking-action are convenient but the raw CLI calls above work without them.

Per-PR failure comment

      - if: failure()
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: proto-gate
          message: |
            ❌ `buf breaking` failed. See log:
            ```
            ${{ steps.breaking.outputs.stdout }}
            ```
            Consult
            references/versioning-strategy.md
            for whether this change is genuinely required and how
            to do it safely (reserve, add new, deprecate old).

Protobuf versioning + breaking-change rules

Protobuf3 schema evolution is a wire-format problem first and a codegen problem second. The field number is the only durable identifier - every breaking-change rule derives from preserving field-number → type binding.

Per protobuf.dev/programming-guides/proto3/ (opens in new window): "This number cannot be changed once your message type is in use because it identifies the field in the message wire format."

This is the catalog of what is breaking and why; the host SKILL.md is the detection workflow (buf breaking in CI).

When to use

• Designing a proto change - is this safe?
• Auditing an existing schema for risky patterns (un-reserved deleted fields, oneof-conversion footguns).
• Configuring buf breaking - which category fits the deployment model?
• PR review of .proto changes.

Field-number rules

When deleting a field, reserve its number:

message User {
  reserved 4, 7, 10 to 12;
  reserved "deprecated_email";

  string name = 1;
  // ...
}

Per the spec: "If you do not reserve the field number, it is possible for a developer to reuse that number in the future." Reuse → semantic corruption: old clients interpret bytes as the old type.

Binary wire-safe changes

Fully safe - old code parses new messages and vice versa with no loss:

Wire-compatible changes (conditionally safe)

These preserve wire compatibility but may be lossy or surprising:

The catch: a parser reading int64 data with int32 will silently truncate. The wire is "compatible" but the data may be lost.

Wire-incompatible changes (always breaking)

• Changing field numbers is equivalent to deleting and re-adding. Always breaks.
• Moving fields into an existing oneof is not safe.
• Changing map<k,v> key or value type.
• Changing field cardinality from singular to repeated (or vice versa) outside the wire-compatible paths.

Oneof constraints

Per protobuf.dev (opens in new window):

• Oneof fields cannot be repeated or map.
• "If multiple values are set, the last set value as determined by the order in the proto will overwrite all previous ones."
• Adding a field to an existing oneof is always breaking - old code can't represent the new variant; new data crashes old parsers.
• Removing a field from a oneof is breaking for the same reason.
• Converting a singular field into a single-field oneof: safe.
• Converting a single-field oneof back to singular: safe.

Map constraints

Per protobuf3 docs:

• Maps cannot be repeated.
• Key types: integral and string scalars only. "neither enum nor proto messages are valid for key_type."
• Changing a map's key or value type is breaking.

buf breaking-change taxonomy

Per buf.build/docs/breaking/rules (opens in new window), buf organises detection into four categories, strictest to most lenient. Full rule-ID tables: buf-breaking-rules.md (opens in new window).

• FILE (default) - "changes that move generated code between files, breaking generated source code on a per-file basis" (e.g. MESSAGE_NO_DELETE, FIELD_SAME_TYPE, FIELD_SAME_CARDINALITY). Choose when codegen consumers import per-file (most JVM, .NET, generated stubs in a monorepo).
• PACKAGE - breakage at package level; permits file relocations inside a package (e.g. PACKAGE_MESSAGE_NO_DELETE). Choose when consumers import by package (Go, Python).
• WIRE_JSON - "changes that break wire (binary) or JSON encoding" (e.g. FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED, FIELD_SAME_JSON_NAME). Choose when consumers use both binary and JSON encoding (REST gateway + grpc).
• WIRE (most lenient) - only changes "compromising binary wire format compatibility" (e.g. FIELD_WIRE_COMPATIBLE_TYPE, allowing int32->int64). Choose when only wire format matters (binary-only protocols between server fleets you control).

Choosing the category

# buf.yaml
version: v2
breaking:
  use:
    - FILE        # most strict (default)
# OR
    - PACKAGE     # codegen friendly within-package
# OR
    - WIRE_JSON   # wire + JSON
# OR
    - WIRE        # wire only

CI invocation:

buf breaking --against ".git#branch=main"
# Compares the working tree against the main branch as baseline

Common patterns

Removing a field

Always reserve the number and the name:

 message User {
+  reserved 2;
+  reserved "nickname";
   string name = 1;
-  string nickname = 2;
 }

More worked diffs - adding an optional field, renaming, promoting int32 to int64, and the oneof footgun: buf-breaking-rules.md (opens in new window).

Anti-patterns

Limitations

• buf categories cover binary breakage. Semantic breakage (a field's meaning changes) is not detectable. Document semantic changes in commit messages.
• JSON name changes (camelCase ↔ snake_case) detected only in WIRE_JSON.
• No transitive analysis. A message field whose type is an imported message: buf doesn't follow the import.
• Doesn't enforce naming conventions. buf lint is separate from buf breaking.

References

• protobuf3 versioning rules: protobuf.dev/programming-guides/proto3/ (opens in new window).
• buf breaking-change rules: buf.build/docs/breaking/rules (opens in new window).
• Consumed by the host skill buf-cli-lint-breaking-build and grpc-streaming-test-author.
• For protobuf-schema contract-testing across services see protobuf-compat-checking.