This feature is only available to organizations on the Enterprise plan.

Buf's breaking change policy enforcement includes a review flow, so that when developers attempt to push breaking changes to the Buf Schema Registry (BSR), commits can be approved or rejected by code owners instead of being rejected outright. This gives downstream consumers protection from breaking schema changes, but allows for nuance in cases where breaking changes are acceptable.

This document walks reviewers through the flow, showing how to review commits and what the downstream implications of review decisions are. It assumes breaking change policy enforcement is enabled at the BSR server level, and that the reviewer is a repository owner or admin. See the feature overview for information about how to enable the review flow.

How commits enter the review flow

With breaking change enforcement enabled, pushing a breaking change to the repository's main branch in the BSR causes the commit to go into a "pending" state. The Buf CLI prints a warning message to the committer, and the BSR sends an in-app notification and email to notify repository owners that a commit needs to be reviewed.

Commits that require approval are annotated as such in the module's Activity tab, and all users see a prominent banner indicating that the module requires attention.

Effects on downstream consumers

Any commits pushed after a commit that's pending are also set to pending, whether or not those commits are breaking changes. Pending commits are unavailable to downstream consumers while the breaking change awaits review, and rejected commits are always unavailable, as follows:

• They're not available to install from any generated SDK registry, by commit name or tag
  • The "latest" version of a generated SDK is kept at the latest approved or non-reviewed commit
• They're not available to use in Buf Studio
• They're excluded from the Reflection API
• They don't update schemas in the Confluence Schema Registry

Reviewing commits

Reviewers work through any pending changes one by one, and approve or reject each commit. Reviewing a commit is a one-way street—once reviewed, the commit stays approved or rejected forever. The result of the review is marked for posterity in the activity tab.

To review breaking commits:

1. Click the Review changes button in the notification, or go to the Activity tab for your module and click the Review changes button for the individual commit.

   The commit with the breaking change and any other commits that may have stacked up behind it are shown in a queue on the left. The first commit's diff is shown in the center of the page, along with inline comments flagging each breaking change.

   

   The diff compares the breaking commit to the latest available commit on `main'. It's important to remember this after rejecting a commit or several—any future commits won't diff against previously rejected commits, but the latest in the repository.

For each breaking change, you have two choices:

• Approve the breaking change, indicating that the change was deliberate and that any breakage with downstream clients is acceptable.
• Reject the breaking change and continue preventing downstream consumers from accessing the commit, marking it as Rejected on the Activity tab. A follow-up change is usually required from the committer after this, such as reverting the bad commit in git or patching it another way.

If additional commits require review, you're taken through each one in the order they were pushed. You can exit the flow at any time and come back to it later without losing completed reviews. Once commits have been reviewed, the original committers will receive emails notifying them that their commits have been evaluated, and the module's Activity tab will reflect the review state of each commit.

Auto-resolved commits

When a commit has been pushed with a breaking change, additional commits may stack up behind it until the breaking change is resolved. The BSR auto-resolves commits where possible, according to the following rules:

• When you approve a breaking change, either:
  • It will become available on the latest main branch, and be marked as Approved on the Activity tab.
  • If there are other pending commits stacked up behind the breaking change, the BSR will auto-approve them up to the next breaking change, and the last of those commits will be the latest on the main branch.
• If you reject a commit and another commit is pushed that fixes the breaking change, any commits between the breaking change and the fix commit will be rejected. The fix commit becomes available on the latest main branch.

Related docs

• Read the overview
• Browse the breaking change rules and categories