Motivation
The tree has many .proto files (controlplane/ynpb, common/commonpb, common/filterpb, per-module *pb, device schemas). Without an explicit v1 compatibility policy, teams cannot agree on what edits are safe (additive only) vs breaking, and tooling like buf breaking needs a declared baseline.
Scope
- Inventory major API surfaces (gateway core protos, shared
commonpb/filterpb, module public RPCs).
- Agree on rules: field number stability, use of
reserved after field removal, deprecation comments, package and go_package conventions, when bumping service or message names is allowed.
- Define what “v1 frozen” means per package (single cutover vs phased).
- Align with the CI breaking checks once #573 (or follow-up work) lands.
Possible solution
Short written policy next to future buf.yaml or in a dedicated doc in-repo; checklist for PR authors (“additive change template”). Optional: one-time audit PR fixing obvious inconsistencies (duplicate meanings, unclear package names) without wire breaks.
Definition of done
Published policy, owners understand additive vs breaking workflow; roadmap item “proto v1” has a concrete checklist; follow-up issues filed for any large cleanups.
Alternatives
Per-module v1 dates instead of one global flag.
Motivation
The tree has many
.protofiles (controlplane/ynpb,common/commonpb,common/filterpb, per-module*pb, device schemas). Without an explicit v1 compatibility policy, teams cannot agree on what edits are safe (additive only) vs breaking, and tooling likebuf breakingneeds a declared baseline.Scope
commonpb/filterpb, module public RPCs).reservedafter field removal, deprecation comments, package andgo_packageconventions, when bumping service or message names is allowed.Possible solution
Short written policy next to future
buf.yamlor in a dedicated doc in-repo; checklist for PR authors (“additive change template”). Optional: one-time audit PR fixing obvious inconsistencies (duplicate meanings, unclear package names) without wire breaks.Definition of done
Published policy, owners understand additive vs breaking workflow; roadmap item “proto v1” has a concrete checklist; follow-up issues filed for any large cleanups.
Alternatives
Per-module v1 dates instead of one global flag.