Skip to content

feat(api): protobuf v1 baseline and compatibility policy #574

@3Hren

Description

@3Hren

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions