Contract versioning: evolve by addition, reserve dead tags, let buf breaking guard the wire

Addition is the only safe verb

If you have ever wondered why a protobuf schema can be updated without coordinating every team at once — the answer is two decoder rules that make most changes invisible to old readers.

The previous lesson established that tags are the wire identity. Versioning follows from two decoder rules. Unknown fields are skipped, not rejected: an old reader hitting a tag it does not know reads past it using the wire type (and modern proto3 preserves those bytes through a re-serialize, so proxies do not strip data). Absent fields read as defaults: a new reader of an old message sees zero, empty string, false. Put together: adding a field with a fresh tag is safe in both directions, and producer and consumer can deploy in either order — the property that makes independent service deployment possible at all.

message Order {
  string order_id = 1;
  int64 total_cents = 2;
  string promo_code = 7;            // new field, new tag — safe both ways
  optional int32 rating = 8;        // explicit presence: unset vs 0 distinguishable
}

The optional line is doing real work. Plain proto3 scalars have no presence: a rating of 0 and a never-set rating serialize identically, which is poisonous for “user gave zero stars” versus “user has not rated”. The optional keyword restores explicit presence — in Go the generated field becomes a pointer and you get a has-check. This is also the answer to where required went: proto3 removed it because a required field is a contract you can never unwind. The moment one required field ships, no writer may ever omit it and no schema may ever drop it — every old reader hard-rejects the message. Requiredness is validation, and validation belongs in application code that can evolve, not in the wire format that cannot.

The forbidden moves, and how a field actually retires

Three changes break the contract, in ascending order of nastiness:

• Changing a type — sometimes loud, sometimes quiet. string to int64 changes the wire type and old data fails to parse or arrives as garbage. The quiet version: int32 and int64 share a wire type, so nothing errors — but an old int32 reader of a value past 2³¹ silently truncates it.
• Changing a tag — the field becomes, on the wire, a different field. Every already-written message and every not-yet-deployed writer now disagrees with you.
• Reusing a deleted tag — the Hook. Old data and lagging writers still emit the tag with its old meaning; if the types are wire-compatible the decoder cannot even notice. This is the only corruption here that is invisible to both the compiler and the runtime.

Notice that all three failures share a pattern: they create a split reality where old and new data carry the same tag with different meanings. When you spot a data anomaly that correlates with a schema change but has no runtime error, one of these three is almost certainly the cause.

Because deletion creates the reuse hazard, deletion is a process, not an edit. Mark the field [deprecated = true] so generated code warns consumers. Migrate writers until nothing emits it. Only then delete — and in the same commit, retire the identity forever:

message Order {
  reserved 5;                   // tag can never be reassigned — compile error
  reserved "discount_cents";    // name too: protects JSON mapping reuse
  string order_id = 1;
  int64 total_cents = 2;
}

With reserved 5; in place, September’s risk_score = 5 is a protoc error at the fraud engineer’s desk instead of three weeks of poisoned decisions.

Fork versus evolve — and the gate that actually enforces all this

Additive evolution has a ceiling: when the meaning of the data changes — amounts move from cents to a decimal type, one message splits into three, a resource is remodeled — patching fields one at a time leaves both halves of the team confused about what a message means. That is what package versions are for: package checkout.v1; and package checkout.v2; are distinct types and distinct services that can be served side by side from one binary. Consumers migrate at their own pace; v1 gets a deprecation window and a shutdown date. Fork when meaning changes; evolve when you are only adding. A v2 is expensive — you will run both for months — so teams that fork over a renamed field are paying for ceremony, and teams that “evolve” a semantic change are shipping the Hook with extra steps.

None of this survives contact with a hurried Friday merge unless a machine checks it. That is buf breaking in CI:

# .github/workflows/proto.yml — the actual gate
- uses: bufbuild/buf-action@v1
  with:
    breaking_against: "https://github.com/acme/protos.git#branch=main"

buf breaking diffs your proto against the live contract and fails the PR on tag reuse, type changes, field deletion without reserved — the whole forbidden list, at the WIRE level or the stricter FILE level that also protects generated-code compatibility. Human review misses a reused tag; the diff looks like a clean addition. The machine does not. The same logic argues for treating protos as a first-class shared artifact — one repo or a schema registry (the Buf Schema Registry is the hosted version), with consumer teams as required reviewers on contract changes. The schema is the one piece of code whose blast radius is every service that speaks it.