Handling Backward Compatibility

1. Adding New Fields Safely

Rule	Detail
Pick new tag	Unused number — never reuse
Default behavior	Old clients ignore unknown fields
Don't change semantics	Of existing fields

message User {
  string name = 1 [deprecated = true];
  string display_name = 4;
}

Step	Detail
Mark deprecated	Codegen warns on use
Document replacement	In proto comment
Remove later	Only after all clients migrated

message User {
  reserved 2, 3, 7 to 10;
  reserved "email", "phone";
}

Strategy	Detail
Package version	`user.v1`, `user.v2`
Run side-by-side	Until v1 deprecated
Avoid in-place breaking change	Always cut new version

Change	Safe?
Add optional field	Yes
Remove field	Reserve number — yes
Change type	No (mostly)
Rename field	Yes (wire uses number) — bad for JSON consumers
Change cardinality	Repeated ↔ singular: NO

buf breaking --against '.git#branch=main'

Step	Detail
Dual-publish	v1 and v2 simultaneously
Adapter layer	Server proxies v1 → v2 internally
Feature flag	Toggle client version

Phase	Detail
Announce	Sunset header + docs
Warn	Log per-call deprecation
Block 0%/10%/100%	Gradual rollout of unavailability
Remove	Delete package; cannot be undone