Overview
This release reduces dependencies on other modules, enforces strict behavior with generated Go packages and name conflicts, expands support for aberrant message types, and provides minor new features in protobuf reflection.
Notable changes
New features:
- CL/242377: proto: add MessageName helper
- CL/236777: reflect/protoreflect: add MessageFieldTypes
- CL/239838: reflect/protoreflect: add FieldDescriptor.TextName
- CL/238000: reflect/protoreflect: improve source information usability
Behavior changes:
- CL/240017: internal/impl: introduce instability to protoreflect.Message.Range order
- CL/262681: internal/encoding/text: escape \x7f (DEL) in strings
- CL/262682: internal/encoding/text: escape Unicode control characters in strings
- CL/259900: internal/filedesc: remove ProtoLegacyRawDesc method
- CL/286132: internal/descfmt: always include type name in FormatList
- CL/302330: cmd/protoc-gen-go: support --help flag
- CL/301952: cmd/protoc-gen-go: print version to stdout
- CL/244297: all: return less-specific, but more informative wire unmarshal errors
Bug fixes:
- CL/247458: testing/protocmp: fix representation of empty bytes
- CL/241658: testing/prototest: fix suggestion for field name
- CL/259899: reflect/protodesc: fix round-tripping for package field
- CL/247737: encoding/protojson: restrict valid values for google.protobuf.Value.number_value
- CL/246097: types/known/fieldmaskpb: repeated and map fields are only valid in the last position of a path
- CL/244718: internal/impl: make errInvalidUTF8 be a proto.Error
Performance optimizations:
- CL/253100: proto/equal: reduce equal scalar value allocation
- CL/240378: reflect/protoregistry: avoid checking for '/' in FindMessageByName
Reduced dependencies
- CL/259901: cmd/protoc-gen-go: remove reference to legacy ProtoPackageIsVersion4
- CL/262679: all: rely on dynamic dependency check for genproto
- CL/262683: all: remove weak dependency on github.com/golang/protobuf
- CL/262684: all: add weak dependency on github.com/golang/protobuf
- CL/235283: all: update protobuf toolchain dependency
Go code generated by protoc-gen-go no longer have a hard dependency on the github.com/golang/protobuf module. In previous releases, the generator would emit a reference to the ProtoPackageIsVersion4 constant to statically enforce that a sufficiently new version of the older module was being linked in. In the last year, most of the Go ecosystem has moved to Go modules, where we can rely on Go modules to enforce a minimum version constraint on the older protobuf module. While there continues to be a cyclic dependency between the github.com/golang/protobuf and google.golang.org/protobuf modules, the cyclic dependency was briefly broken and re-added to clear out the infinitely growing list of go.sum entries.
The module dependency on the google.golang.org/genproto module has been removed. Any program that depends on both google.golang.org/protobuf and google.golang.org/genproto must use at least version cb27e3aa from May 26th, 2020. There is a runtime check at program initialization that panics when too old of a version of the genproto module is being linked into the binary.
The well-known types provided by this module are built from v3.15.3 of the protobuf toolchain.
Require Go import path
- CL/301953: compiler/protogen: require that the import path be specified
As mentioned in the v1.20.0 release from March 2nd, 2020, the Go generator will require that the Go import path be specified for all .proto files being generated and their transitive dependencies. Since v1.20.0, every occurrence of a .proto file missing a Go import path has resulted in a warning being printed to standard error that this will eventually become a fatal error. The Go import path is normally specified by declaring a go_package option in the .proto file. Alternatively, this can be specified at compile-time with a M flag passed on the command line. See the developer documentation for more information on the go_package option and M flag.
Fatal namespace conflicts
- CL/235298: reflect/protoregistry: panic upon registration conflicts
- CL/295349: reflect/protoregistry: add compile-time opt-out for registration conflicts
As mentioned in the v1.20.0 release from March 2nd, 2020, the Go protobuf runtime will fatally fail if it detects the registration of duplicate names. Since v1.20.0, every occurrence of a conflict has resulted in a warning being printed to standard error that this will eventually become a fatal error. See the developer documentation for more information about what a namespace conflict is and how to resolve it.
While it is preferable that the source of the conflict be fixed, the fatal error can be immediately worked around in one of two ways:
- At compile time. The default behavior for handling conflicts can be specified at compile time with a linker-initialized variable:
go build -ldflags "-X google.golang.org/protobuf/reflect/protoregistry.conflictPolicy=warn"
- At program execution. The behavior for handling conflicts when executing a particular Go binary can be set with an environment variable:
GOLANG_PROTOBUF_REGISTRATION_CONFLICT=warn ./main
This will cause the runtime to use the conflict handling behavior from v1.25.0 and earlier, which is to simply warn about them.
Support for aberrant message types
- CL/300869: internal/impl: add runtime support for aberrant messages
- CL/244937: internal/impl: add runtime support for *[]byte unknown representation
This project's compatibility document specifies that we only guarantee runtime compatibility with messages generated by protoc-gen-go. Use of this module's runtime with any other custom message type will have mixed results, ranging from panics, to unspecified behavior, to working correctly. The proper way for custom message types to perfectly work with this module is for the custom type to implement the protoreflect.ProtoMessage interface, which allows a given message implementation to self-describe how its contents should be introspected.
Since some widely depended upon modules have custom message types not generated by protoc-gen-go, we expand support in this module's runtime to be able to handle those aberrant message types. This change should reduce the probability that using one of those modules with this module results in a panic and instead have reasonably correct behavior.
This support is not covered by this project's compatibility guarantee and may be modified or removed in a future version of this module without notice. Custom types must move to supporting protobuf reflection to ensure long-term compatibility.
Upcoming breakage changes
This release makes some potentially disruptive changes that have been announced since the v1.20.0 release on March 2nd, 2020. Not all breaking changes mentioned in the v1.20.0 have been made and may still take effect in a later version of this module.
There are no new upcoming breaking changes to announce in this release.