Skip to content

Breaking change detection – Overview#

This page provides an overview of Buf's breaking change detection. At every step of the development process, starting with developer IDEs and culminating in the Buf Schema Registry's instance-wide enforcement, breaking change detection ensures that your organization can evolve Protobuf schemas quickly and safely.

Protobuf has many ways to evolve schemas without breaking existing code. Many of Buf's breaking change rules maximize your evolution options to do exactly that. However, sometimes it's a better choice to make a breaking change rather than go to the extra effort of backwards compatibility. If you have few clients and can easily update and deploy them, it may be perfectly okay to break your schemas. And if you have a public API or too many clients to easily update, you should probably avoid breaking them.

Whichever path you choose, Buf's breaking change detection allows you to make informed decisions, while removing the need for constant vigilance during code review. It reliably and mechanically identifies breaking changes so you and your team can focus on making an informed decision about whether to allow them or not.

Key concepts#

Buf's breaking change detection evaluates your schemas' compatibility at three phases of development:

  • During development: You can spot-check in your local environment by running buf breaking.
  • In code review: You can integrate with your CI/CD workflows (like GitHub Actions) to ensure that breaking changes get flagged directly in your review flow.
  • When shipping to the Buf Schema Registry (BSR): This makes them available to other teams and downstream systems like Kafka. The BSR lets your organization enforce checks that prevent developers from committing unintended breaking changes to the BSR. Instead, they go to a review flow so that the repository owners can review the changes and approve or reject them before they enter your production environment.

buf breaking runs a set of compatibility checks comparing the current version of your Protobuf schema to a past version. The past version can be any type of input that the Buf CLI accepts, such as a BSR module, a GitHub repo, or a Buf image.

The checker has a built-in set of rules and categories and can also accept rules and categories via Buf check plugins. You can use them alongside or in place of Buf's defaults.

Rules and categories#

The checker's categories reflect the nature of the breaking changes, so choosing a strictness level is straightforward. You can also select rules individually to more closely match your organization's policies. See the rules and categories page for detailed information.

The configuration categories, from strictest to most lenient, are:

  • FILE: Default. Detects generated source code breakage on a per-file basis
  • PACKAGE: Detects generated source code breakage on a per-package basis
  • WIRE_JSON: Detects breakage to wire (binary) or JSON encoding
  • WIRE: Detects breakage to wire (binary) encoding

Changes that pass breaking change detection under a stricter policy also pass with all less-strict policies. For example, passing the FILE rules means you also pass the PACKAGE rules.

Next steps#