Protobuf: APIv2: track breaking changes
This is a meta-issue for tracking any breaking changes that occur before the final v2 release. Since v2 is not yet released, we reserve the right to make breaking changes to improve the API to be as good as it can be.
The CL (changelist) that introduces a breaking change will be posted here as a comment. Subscribe to this issue to be notified of breakages. We try to batch multiple breaking changes close together in time to reduce user churn.
dsnet
All 29 comments
Is there any rough idea of when api-v2 will become stable/available/recommended?
robbertvanginkel
on 13 Jun 2019
We're aspirationally aiming for GopherCon 2019, which would be the end of July. However, this is aspirational. If the v2 work is not where we would like it to be (i.e., incomplete, buggy, etc...), then we will delay. We estimate that the amount of work left is on the order of months, not years.
dsnet
on 13 Jun 2019
Breaking changes:
- CL/182537: reflect/protoregistry: remove Files.RangeFilesByPath method
- CL/175987: reflect/protoreflect: remove bool output for Descriptor.Parent method
- CL/176942: reflect/protoreflect: remove FieldDescriptor.{Oneof,Extendee} methods
- CL/174938: reflect/protoreflect: remove {Enum,Message}.Type methods
- CL/182597: reflect/protoreflect: remove KnownFields and UnknownFields interfaces
dsnet
on 17 Jun 2019
Minor change:
- CL/182638: reflect/protodesc: use Resolver interface
dsnet
on 19 Jun 2019
Exceedingly minor change:
- CL/182980: encoding/proto{json,text}.MarshalOptions.Resolver must also resolve extensions
neild
on 19 Jun 2019
Minor change:
- CL/183101: internal/fileinit: remove package
This only affects generated code; the fix is to regenerate the .pb.go files.
dsnet
on 21 Jun 2019
Breaking change:
- CL/183700: reflect/protoregistry: remove Files.Find{Enum,Message,Extension,Service}ByName
dsnet
on 25 Jun 2019
Breaking change:
- CL/183678: all: remove protoreflect.Message.Len
neild
on 25 Jun 2019
Behavior change:
- CL/184837: reflect/protodesc: enforce strict validation
This CL enforces that the input file descriptors are well-formed according to the same rules as the C++ protoc implementation.
dsnet
on 3 Jul 2019
@dsnet Is there a new estimate on the release date of v2?
We're looking at evaluating replacing golang/protobuf over gogo/protobuf in the context of https://github.com/envoyproxy/data-plane-api (cc @htuch).
kyessenov
on 1 Aug 2019
@kyessenov We don't have a solid date yet, although I'm pretty confident in saying "before the end of the year".
neild
on 5 Aug 2019
Unfortunately we are behind schedule on v2 release. It should occur shortly after all issues with the "blocks-v2" label are resolved. We still hope that it happens within a month or two, but should definitely happen before the end of the year.
One of the ways that we have confidence in the quality of the v2 release is that we switch most of production Go code at Google to be using the v2 implementation internally. However, this effort is taking longer than expected due to the need to support a variety of legacy and deprecated features. If you have additional questions/comments about the release process for v2, please file another issue.
Since there are a number of people subscribed to this thread, I'm locking this thread so that only updates about breaking changes are posted from here on out.
dsnet
on 5 Aug 2019
- CL/187857: reflect/prototype: drop Extension
The rest of the prototype package will probably follow soon.
neild
on 6 Aug 2019
- CL/189198: compiler/protogen, cmd/protoc-gen-go: use alternative comments API
dsnet
on 7 Aug 2019
Breaking changes:
- CL/189199: all: refactor extensions, add proto.GetExtension etc.
This CL changes the protoreflect.{Message,Enum,Extension}Type types to no longer implement the corresponding Descriptor interface. (They still have a has-a relationship with the descriptor.)
Accessing extension fields in a protoreflect.Message now requires a protoreflect.ExtensionTypeDescriptor (which implements FieldDescriptor) instead of an ExtensionType (which doesn't any more). ExtensionType.Descriptor returns an ExtensionTypeDescriptor.
- CL/189340: all: drop reflect/prototype package
The prototype package is removed as unnecessary.
neild
on 8 Aug 2019
Breaking change:
- CL/189563: all: unify protoV1.ExtensionDesc and proto.ExtensionType
- CL/189564: internal/impl: clean up obsolete ExtensionInfo fields/funcs
The protoiface.ExtensionDescV1 type is removed. (And lots of other internal refactoring, but I believe that's the only breaking API change.) This is unlikely to affect anyone.
neild
on 21 Aug 2019
Minor breaking change:
- CL/191039: compiler/protogen: export Plugin.FilesByPath
dsnet
on 21 Aug 2019
Breaking change:
- CL/192139: rename ExtensionType Descriptor method to TypeDescriptor
This is a fiddly change, but improves clarity a bit around the very subtle interactions between the various views of an extension.
neild
on 28 Aug 2019
Breaking change:
- CL/193598: remove NewMessage methods
Superseded by the more general-purpose Message.NewField, List.NewElement, and Map.NewValue.
neild
on 5 Sep 2019
Breaking change:
- CL/199060: remove {Enum,Message,Extension}Type.GoType methods
Removed to simplify the interface, and because there are now better ways to do just about everything they were used for.
neild
on 9 Oct 2019
Minor breaking change:
- CL/204897: remove nullability from repeated extension fields
m.Has(extensionTypeDescriptor) will now return false for a zero-length repeated extension field.
neild
on 5 Nov 2019
Breaking change:
- CL/206017: remove deprecated APIs
The (*Files).Register and (*Types).Register functions in the protoregistry package have been replaced by type-safe Register{File,Enum,Message,Extension} methods.
The protoregistry.NewFiles and protoregistry.NewTypes functions are gone. (Just call Register...)
The protoregistry.Type type is removed (nothing references it any more).
neild
on 8 Nov 2019
Minor breaking change:
- CL/207077: testing/protocmp: switch Enum.Number to be a method
dsnet
on 13 Nov 2019
- CL/209018: reflect/protoreflect: add {Message,List,Map}.IsValid
- CL/209019: all: fix reflection behavior for empty lists and maps
Minor addition to some protoreflect types, only affecting implementations of those types.
Brought reflection behavior for empty lists and maps in line with documentation. Technically not a breaking change (just doing what the documentation said!), but it would have been easy to depend on the previous behavior by accident.
neild
on 27 Nov 2019
- CL/215718: all: add ProtoMethods method to protoreflect.Message
- CL/215719: all: abstract fast-path marshal and unmarshal inputs and outputs
Changes to the fast-path ProtoUnmarshal method: It moves into the protoreflect.Message interface, and the method signature changes a bit.
Performance improvement (avoids an interface->interface type conversion, which is expensive) and future-proofing.
neild
on 21 Jan 2020
- CL/219145: proto: remove shallow merge support, and MergeOptions
Shallow merges were well-defined, but we're debating whether that definition is useful. Dropped support for shallow merges for now, since this isn't a v1 feature we need to preserve.
neild
on 12 Feb 2020
- CL/220117: reflect/protoreflect: add List.AppendMutable and Map.Mutable
Convenience methods on protoreflect's List and Map types.
neild
on 19 Feb 2020
- CL/219505: all: fast-path method refactoring
One last change to the fast-path method signatures, for consistency and future expansion.
neild
on 19 Feb 2020
APIv2 is released. No more breaking changes!
neild
on 3 Mar 2020
Related issues
hxzqlh
路
5Comments
zamberform
路
5Comments
occho
路
5Comments
jhump
路
5Comments
junghoahnsc
路
5Comments
Most helpful comment
We're aspirationally aiming for GopherCon 2019, which would be the end of July. However, this is aspirational. If the v2 work is not where we would like it to be (i.e., incomplete, buggy, etc...), then we will delay. We estimate that the amount of work left is on the order of months, not years.