70:T26a6,* [Overview](#v1.4-overview) * [Backwards compatibility](#v1.4-backwards-compatibility) * [Notable changes](#v1.4-notable-changes) * [Wire serialization](#v1.4-wire-serialization) * [JSON and text serialization](#v1.4-json-text-serialization) * [Well-known types](#v1.4-well-known-types) * [Types registry](#v1.4-types-registry) * [Nil values](#v1.4-nil-values) * [Errors](#v1.4-errors) * [Generated code](#v1.4-generated-code) * [Upcoming breakage changes](#v1.4-breaking-changes) * [Deprecation of `Descriptor` methods](#v1.4-deprecated-descriptor) * [Removal of `generator` package](#v1.4-remove-generator) # Overview This release of the [`github.com/golang/protobuf`](https://pkg.go.dev/mod/github.com/golang/protobuf) module introduces a number of significant changes relative to the previous minor release. In particular, this module is now implemented in terms of the new [`google.golang.org/protobuf`](https://pkg.go.dev/mod/google.golang.org/protobuf) module, which is the next major revision of Go bindings for protocol buffers. From this point onwards, most of the development effort for Go protobufs will be dedicated to the new module, with minimal changes being made to this module. See the [release notes for the new module](https://github.com/protocolbuffers/protobuf-go/releases/tag/v1.20.0) for specific implementation details that may affect this release. ## Backwards compatibility This release maintains backwards compatibility with previous releases of this module. Any observable changes in behavior are to fix bugs, change unspecified behavior, or to make behavior more compliant with the protobuf specification. The [compatibility document](https://github.com/golang/protobuf#compatibility) provides us the freedom to make changes in these areas. # Notable changes ## Wire serialization Wire serialization is now implemented in terms of the new [`proto`](https://pkg.go.dev/google.golang.org/protobuf/proto) package by calling out to the relevant functionality in that package (e.g., [`proto.Marshal`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Marshal) and [`proto.Unmarshal`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Unmarshal)). There should be no observable changes in behavior other what is mentioned elsewhere in the release notes (e.g., behavior around [errors](#v1.4-errors) or [nil values](#v1.4-nil-values)). ## JSON and text serialization The JSON and text format implementations have been ported to use [protobuf reflection](https://github.com/protocolbuffers/protobuf-go/releases/tag/v1.20.0#v1.20-reflection) under the hood instead of relying on Go reflection. This provides flexibility as they can operate on any concrete message type that properly implements the new [`proto.Message`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message) interface. The implementations do _not_ use the new [`protojson`](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson?tab=doc#Message) or [`prototext`](https://pkg.go.dev/google.golang.org/protobuf/encoding/prototext?tab=doc#Message) packages in order to maintain a higher degree of backwards compatibility. Our analysis unfortunately showed us that too many tests rely on their output being stable by performing byte-for-byte comparisons. Even though the compatibility promise gives us the freedom to change the output, we have chosen not to do so for pragmatic reasons. The implementations are now functionally frozen (bugs and all) and will not receive future improvements. Users are encouraged to migrate to the `protojson` or `prototext` packages instead. ## Well-known types The well-known types declared under [`ptypes`](https://pkg.go.dev/github.com/golang/protobuf/ptypes?tab=subdirectories) are moved to the `google.golang.org/protobuf` module. The packages continue to exist, but all declarations forward to [ones in the new module](https://pkg.go.dev/google.golang.org/protobuf/types/known?tab=subdirectories). For a period of time, it is expected that the [`protoc-gen-go`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go) plugin continues to generate code with dependencies on the well-known types in this module. The import paths for the well-known types are determined by the `go_package` option specified in the `.proto` files. Since these files are managed by the main protocol buffers project, it will require a new release of the protobuf toolchain before the new import paths take effect. Depending on this module’s packages for well-known types is fine since they simply forward over to the new packages. While [`descriptor`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/descriptor) and [`plugin`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/plugin) are not packages for well-known types, they too have also been moved to the new module. ## Types registry In order for dynamic usages of protobufs to operate correctly, there must be a unified registry between this module and the new `google.golang.org/protobuf` module. The [`protoregistry`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoregistry) package is the primary registry for all protobuf files that are linked into a Go program. The registration functions (e.g., [`proto.RegisterType`](https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#RegisterType)) in this package forward to the global registries in that module, and the lookup functions (e.g., [`proto.MessageType`](https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#MessageType)) in this package source from the global registries in that module. ## Nil values Use of the `google.golang.org/protobuf` module for the underlying implementation means that semantics for nil values may have changed. See [that module’s release notes](https://github.com/protocolbuffers/protobuf-go/releases/tag/v1.20.0#v1.20-nil-values) for details. ## Errors A consequence of using the `google.golang.org/protobuf` module as the underlying implementation means that the text for some errors may change in trivial ways. This may break brittle tests depending on the error message. See [that module’s release notes](https://github.com/protocolbuffers/protobuf-go/releases/tag/v1.20.0#v1.20-errors) for details. ## Generated code The [`protoc-gen-go`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go) plugin in this module is now a thin wrapper over the [`protoc-gen-go`](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go) plugin in the `google.golang.org/protobuf` module. As a result, there are many changes to the generated code. See [that module’s release notes](https://github.com/protocolbuffers/protobuf-go/releases/tag/v1.20.0#v1.20-generated-code) for details. Users should migrate to use the new [`protoc-gen-go`](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go) plugin instead of the old one. Code generated by either plugin should be compatible with either module. For backward compatibility purposes, the `protoc-gen-go` plugin in this module continues to support generation of gRPC bindings, while the [`protoc-gen-go` plugin in the new module does not](https://github.com/protocolbuffers/protobuf-go/releases/tag/v1.20.0#v1.20-grpc-support). # Upcoming breakage changes Per the [compatibility agreement for Go protobufs](https://github.com/golang/protobuf#compatibility), we promise to make announcements about deliberate or potentially breaking changes 6 months in advance. None of these changes are effective yet in this release. ## Deprecation of `Descriptor` methods The [`Descriptor` methods on generated messages are deprecated](https://github.com/protocolbuffers/protobuf-go/releases/tag/v1.20.0#v1.20-deprecated-generated) and may be removed in the future. The [`descriptor.Message`](https://pkg.go.dev/github.com/golang/protobuf/descriptor?tab=doc#Message) type is deprecated as fewer and fewer message types in the future will implement the `descriptor.Message` interface. Existing usages should migrate to the new [`proto.Message`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message) interface. The [`descriptor.ForMessage`](https://pkg.go.dev/github.com/golang/protobuf/descriptor?tab=doc#ForMessage) function is also deprecated. Users should migrate the code to use [protobuf reflection](https://github.com/protocolbuffers/protobuf-go/releases/tag/v1.20.0#v1.20-reflection) to access descriptor information. ## Removal of `generator` package The [`generator`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/generator) package is an internal implementation detail of `protoc-gen-go` and existed before the [internal package mechanism](https://golang.org/doc/go1.4#internalpackages). It has long been exempt from the compatibility promise. A future release of this module will remove the package. Existing users must migrate to the new [`compiler/protogen`](https://pkg.go.dev/google.golang.org/protobuf/compiler/protogen) package, which is a stable API for implementing protoc plugins, or fork the existing `generator` package. Similarly, the [`grpc`](https://pkg.go.dev/github.com/golang/protobuf/protoc-gen-go/grpc) package is also an internal implementation detail of `protoc-gen-go` and will also be deleted in a future release of this module.55:["$","$L6c",null,{"entries":[{"key":["platform",{"userId":"anon"},"repo","releases",{"owner":"golang","repo":"protobuf"},"detail","v1.4.0"],"data":{"id":"224472","version":"v1.4.0","channel":"stable","title":"v1.4.0","publishedAt":"2020-04-13T19:43:07Z","summary":"* [Overview](#v1.4-overview)","notesMarkdown":"$70","attachments":[],"htmlUrl":"https://trylle.com/golang/protobuf/releases/tag/v1.4.0","target":"1b794fe86dd6a0c7c52ae69b5c9cb0aeedc52afa","commitSha":"1b794fe86dd6a0c7c52ae69b5c9cb0aeedc52afa","publisher":{"id":-1,"login":"Ghost"},"zipballUrl":"/v1/repositories/golang/protobuf/archive?ref=v1.4.0&format=zip","tarballUrl":"/v1/repositories/golang/protobuf/archive?ref=v1.4.0&format=tar.gz","isDraft":false,"isPrerelease":false},"fetchedAt":1793418586353}],"children":"$L71"}]