Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Split FIELD_SAME_TYPE into FIELD_SAME_TYPE, FIELD_WIRE_COMPATIBLE_TYPE, FIELD_WIRE_JSON_COMPATIBLE_TYPE #400

Merged
merged 2 commits into from
Aug 6, 2021

Conversation

bufdev
Copy link
Member

@bufdev bufdev commented Aug 6, 2021

Fixes #80
See https://docs.buf.build/breaking-rules/#field_same_type
See https://developers.google.com/protocol-buffers/docs/proto3#updating
See https://developers.google.com/protocol-buffers/docs/proto3#json

Largely in the interest of expediency, but also in the interest of users not thinking about what is and isn't wire-compatible in terms of scalar types, we did not encode the actual wire compatibility rules when checking if a field is the same type if using the WIRE category. It turns out that users noticed this. There was also a legitimate case of someone moving enums from being nested to non-nested, and this being detected as a breaking change.

This PR adds a new breaking rule FIELD_WIRE_COMPATIBLE_TYPE that replaces FIELD_SAME_TYPE for the WIRE category in v1. This does the following:

  • If the type changes between int32, uint32, int64, uint64, and bool, no failure is produced.
  • If the type changes between sint32 and sint64, no failure is produced.
  • If the type changes between fixed32 and sfixed32, no failure is produced.
  • If the type changes between fixed64 and sfixed64, no failure is produced.
  • If the type is changed from string to bytes, no failure is produced.
  • A special message talking about string and bytes compatibility is produced if the type changed from bytes to string. Per the docs, you can change between string and bytes IF the data is valid UTF-8, but since we are only concerned with the API definition and cannot know how a user will actually use the field, we still produce a failure.
  • If the previous and current types are both enums, the enums are checked to see if the (1) the short names are equal (2) the previous enum is a subset of the current enum. A subset is defined as having a subset of the name/number enum values. If the previous is a subset, no failure is produced. The idea here is that this covers if someone just moves where an enum is defined, but still allows values to be added to this enum in the same change, as adding values to an enum is not a breaking change.
  • A link to https://developers.google.com/protocol-buffers/docs/proto3#updating is added to failures produced from FIELD_WIRE_COMPATIBLE_TYPE.

This also adds a new FIELD_WIRE_JSON_COMPATIBLE_TYPE that replaces FIELD_SAME_TYPE for the WIRE_JSON category in v1.

JSON still allows for some exchanging of types, but due to how various fields are serialized, the rules are stricter. See https://developers.google.com/protocol-buffers/docs/proto3#json - for example, int32, sint32, uint32 can be exchanged, but 64-bit numbers have a different representation in JSON. Since sint32 is not compatible with int32 or uint32 in WIRE, we have to limit this to allowing int32 and uint32 to be exchanged in JSON.

This does the following:

  • If the type changes between int32 and uint32, no failure is produced.
  • If the type changes between int64 and uint64, no failure is produced.
  • If the type changes between fixed32 and sfixed32, no failure is produced.
  • If the type changes between fixed64 and sfixed64, no failure is produced.
  • If the previous and current types are both enums, the enums are checked to see if the (1) the short names are equal (2) the previous enum is a subset of the current enum. A subset is defined as having a subset of the name/number enum values. If the previous is a subset, no failure is produced. The idea here is that this covers if someone just moves where an enum is defined, but still allows values to be added to this enum in the same change, as adding values to an enum is not a breaking change.
  • Links to https://developers.google.com/protocol-buffers/docs/proto3#updating and https://developers.google.com/protocol-buffers/docs/proto3#json
    are added to failures produced from FIELD_WIRE_JSON_COMPATIBLE_TYPE.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Changing an enum field to an identical type is considered breaking WIRE change
1 participant