CODEWITHSUNDEEP
protocol-buffers
corgrath
corgrath

Reputation: 12305

Whats the best way to deprecate a field in Protocol Buffer v3, reserved vs deprecated=true?

When using Protocol Buffers version 3, from what I can see, there are 2 ways you can deprecate a field:

Either using the deprecate field using tags:

message MyMessage {
    string deprecated_my_field = 1 [deprecated=true];
}

Or creating a reserved field ID:

message MyMessage {
    reserved 1; // Deprecated "my_field"
}

I am leaning towards reserved since then no one will be able to use the field.

Is this a bad idea?

Upvotes: 20

Views: 23056

Answers (3)

daghan
daghan

Reputation: 1028

First add the deprecated annotation and submit the code:

message MyMessage {
    string deprecated_my_field = 1 [deprecated=true];
}

Then, once you are sure all the usages are cleaned up, remove the field and add reserved:

message MyMessage {
    reserved 1;
}

So it is a 2-step process.

Upvotes: 2

Noel Yap
Noel Yap

Reputation: 19798

One way to view this is that using [ deprecated = true ] actually deprecates the field while using reserve actually obsoletes the field. A big difference between the two is that the latter introduces a backwards-incompatible change and, pedantically, warrants a new version of the proto.

It might also be a good idea to document the deprecated/obsoleted field (including what to use instead if applicable) with something like:

  [
    deprecated = true,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Recipient's name"
    }
  ]

Upvotes: 4

Marc Gravell
Marc Gravell

Reputation: 1063864

Both will work; the first option keeps the definition in the model, so it can still be accessed and queried - but it may generate a build warning when available (for clients who update from the schema). This may have useful applications in some cases.

The second option completely removes the field from the model, so any existing usages will break at build when clients update from the schema. Again, this could be good or bad, depending on how "done" you are with the field.

In some cases, the softer "mark it as a build warning, but allow access" may be preferred; in others, the hard "that doesn't exist!" approach is cleaner. It is subjective.

Either will fundamentally get the job done.

Upvotes: 24

Related Questions