Never reuse a tag number - #550
Conversation
The tag semantics section of the Fields page said the only constraint on tagged fields is to never change the type associated with a tag number. That's incomplete: reusing a tag number with the same type keeps on-the-wire compatibility but breaks the application contract, since applications with the old definition decode the new field as the old one. Fixes icerpc#213 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
InsertCreativityHere
left a comment
InsertCreativityHere
left a comment
There was a problem hiding this comment.
I'd change some of the wording here, but (after going back and forth), I think it is good to mention this fact.
Even though I do find it a little strong at times (since you totally can do this, as long as you know any consumers of the old API are completely gone). But I think that's fine at a documentation level.
| never reuse a tag number: once you define `tag(7) name: string?` in a given tag number scope, tag 7 belongs to this | ||
| field forever, even after you remove the field. Reusing tag 7 with another type breaks on-the-wire compatibility with |
There was a problem hiding this comment.
I think this is more clear, since it states a clear action users should take, and since I don't know what a tag "belonging to a field" means in-of-itself.
| never reuse a tag number: once you define `tag(7) name: string?` in a given tag number scope, tag 7 belongs to this | |
| field forever, even after you remove the field. Reusing tag 7 with another type breaks on-the-wire compatibility with | |
| never reuse a tag number: once you define `tag(7) name: string?` in a given tag number scope, tag 7 should be reserved | |
| forever, even after you remove the field. Reusing tag 7 with another type breaks on-the-wire compatibility with |
There was a problem hiding this comment.
Agreed, "reserved" is clearer. I used "tag 7 stays reserved forever" rather than "should be reserved", since the sentence opens with "you must never".
| You can add, remove and reorder tagged fields over time while maintaining on-the-wire compatibility. However, you must | ||
| never reuse a tag number: once you define `tag(7) name: string?` in a given tag number scope, tag 7 belongs to this | ||
| field forever, even after you remove the field. Reusing tag 7 with another type breaks on-the-wire compatibility with | ||
| applications that expect tag 7 fields to be encoded as strings. Reusing tag 7 with a string but a different meaning |
There was a problem hiding this comment.
I'd rewrite this a little bit:
- on-the-face of it, it sounds like you could have multiple fields all using the same tag.
fields != arguments, so there should only be one field associated withtag(7)in a given context. - it's shorter without losing clarity IMO
- earlier in this same sentence we say "Reusing tag 7 with another type"; no mention of the field.
| applications that expect tag 7 fields to be encoded as strings. Reusing tag 7 with a string but a different meaning | |
| applications that expect tag 7 to be of type `string`. Reusing tag 7 with a string but a different meaning |
There was a problem hiding this comment.
Good point, applied as suggested.
| preserves on-the-wire compatibility but breaks the application contract: applications that use the old definition | ||
| decode the new field as `name`. |
There was a problem hiding this comment.
This sentence doesn't actual explain what the problem is. It just states the fact that it will decode the new field as name, but, no issue is actually presented. Better to clearly state the issue:
| preserves on-the-wire compatibility but breaks the application contract: applications that use the old definition | |
| decode the new field as `name`. | |
| preserves on-the-wire compatibility but breaks the application contract: applications that use the old definition | |
| will still treat the decoded value as `name` instead of its new meaning. |
There was a problem hiding this comment.
Fair. I went with "applications that use the old definition mistake the new field for name", which names the problem in fewer words.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
InsertCreativityHere
left a comment
InsertCreativityHere
left a comment
There was a problem hiding this comment.
Sounds good to me!
3 participants
The Tag semantics section of the Fields page said the only constraint on tagged fields is to never change the type associated with a tag number. That's incomplete: reusing a tag number with the same type keeps on-the-wire compatibility but breaks the application contract, since applications with the old definition decode the new field as the old one.
The rule is now "never reuse a tag number", with both consequences spelled out.
Fixes #213
🤖 Generated with Claude Code