Write up example of a protobuf migration

[illicitonion]

In motivating why protobuf (aside from efficient binary encoding), one of the big ideas is around API evolution, and simplifying coordinating rollouts.

An example I've been using to explain this is the example of migrating a field. For instance with this protobuf:

message PersonResponse {
    string name = 1;
}

to this protobuf:

message PersonResponse {
    string full_name = 1;
    string display_name = 2;
}

and maybe even then to this one:

message PersonResponse {
    reserved 1; // Used to be full_name
    string display_name = 2;
}

(an alternate I've used is making a field repeated)

and having three services (a client, a server, and a proxy in the middle), having to think about things like what order these changes are deployed. Comparing this to a JSON world where these field renames (and possibly not preserving unknown fields when round-tripping in the proxy) introduce a lot more deployment coordination requirement.

We should maybe write up such an example, showing all of the ways things can go wrong if you're not coordinating these rollouts well (including e.g. needing to coordinate rollbacks!), and showing how protobuf (which still requiring thought, as well as following best practices) reduces the space of things that can go wrong.

[chettriyuvraj]

Hi @illicitonion!

I was wondering if Chapter 4: Encoding and Evolution of "Designing Data Intensive Applications" by Martin Kleppman could be suggested as a pre-read to get the 'why' around API evolution/protobufs clear.

It is not too heavy at ~ 28 pages long and I feel it gives a very good feel of how something like protobufs handle schema evolution (and comparisons with something like JSON)

Here's an Ebook link: do have a look if you find the time!