skill-schema-evolution

To detect breaking changes in protobuf schemas before committing, use a local validation workflow with buf tooling and pre-commit hooks based on ADR-0004 guidelines. This enforces safe patterns and catches backward compatibility issues locally before commits.

Backward-compatible protobuf schema evolution is the process of modifying proto definitions by applying safe patterns, such as introducing new fields or event types per BIAN patterns, without breaking existing API consumers.

To introduce new event types in protobuf while maintaining backward compatibility, follow BIAN patterns for schema evolution alongside ADR-0004 guidance to ensure new events do not disrupt existing API workflows.

Yes, buf works with ADR-0004 for local proto validation by providing the tooling and breaking change detection needed to enforce safe schema evolution patterns locally before you commit changes.

The best way to manage API schema evolution without breaking existing consumers is to combine pattern-based backward-compatible guidance with buf breaking change detection and pre-commit validation hooks.

You should use pre-commit hooks for protobuf schema validation to enforce ADR-0004 guidelines and catch breaking changes locally before they enter the repository, ensuring safe schema evolution.