proto-breaking

What problem does it solve?

Prevents accidental Protocol Buffer breaking changes from reaching downstream clients by standardizing how forge projects enforce compatibility and how teams evolve protos over time.

Core Features & Use Cases

• CI breaking-change gate generation: Ensures a Tier-1 GitHub workflow runs buf breaking on PRs that modify proto/**, buf.yaml, or buf.gen.yaml, comparing against main.
• Guided deprecation-to-removal workflow: Covers the 99% path—add the new shape, deprecate the old, migrate callers, then remove safely using reserved to satisfy buf breaking.
• Rare hard-break handling: Describes the version-rev approach (e.g., v1 frozen, new v2 package) and when to use it.
• Legitimate override mechanisms: Provides an auditable [skip-buf-breaking] PR commit marker, targeted buf.yaml ignore entries for single-file exceptions, and cautions against disabling the workflow.
• Local verification matching CI: Shows how to run buf breaking locally against the same baseline as CI for confidence before merging.

Quick Start

Use the proto-breaking skill to generate and follow a deprecation and removal plan that makes buf breaking pass by verifying locally with the same --against baseline as your CI workflow.