Protobuf Stable Version
Milba Vanpatten
Starting with the v20.x protoc release, we changed our versioning scheme toenable nimbler updates to language-specific parts of Protocol Buffers. In thenew scheme, each language has its own major version that can be incrementedindependently of other languages. The minor and patch versions, however, remaincoupled. This allows us to introduce breaking changes into some languageswithout requiring a bump of the major version in languages that do notexperience a breaking change. For example, a single release might include protocversion 24.0, Java runtime version 4.24.0 and C# runtime version 3.24.0.
The first instance of this new versioning scheme was the 4.21.0 version of thePython API, which followed the preceding version, 3.20.1. Other language APIsreleased at the same time were released as 3.21.0.
Protobuf does not consider enforcement of its documented language, tooling,platform, and library support policies to be a breaking change. For example, arelease may drop support for an EOL language version without bumping majorversions.
The binary wire format does not change even in major version updates. Youwill continue to be able to read old binary wire format proto data from newerversions of Protocol Buffers. Newly generated protobuf bindings serialized tobinary wire format will be parseable by older binaries. This is a fundamentaldesign principle of Protocol Buffers. Note that JSON and textproto formats donot offer the same stability guarantees.
The descriptor.proto schema can change. In minor or patch releases, we mayadd new message, fields, enums, enum values, editions, editionsfeatures etc. We may also markexisting elements as deprecated. In a major release, we may remove deprecatedoptions, enums, enum values, messages, fields, etc.
The .proto language grammar can change. In minor or patch releases, we mayadd new language constructs and alternative syntax for existing features. We mayalso mark certain features as deprecated. This could result in new warnings thatwere not previously emitted by protoc. In a major release, we may removesupport for obsolete features, syntax, editions in a way that will requireupdates to client code.
Gencode and runtime APIs can change. In minor or patch releases, changeswill either be purely additive for new functionality or source-compatibleupdates. Simply recompiling code should work. In a major release, the gencode orruntime API can change in incompatible ways that require callsite changes. Wetry to minimize these. Changes fixing or otherwise affecting undefined behaviorare not considered breaking, and do not require a major release.
Operating system, programming language, and tooling version support canchange. In a minor or patch release, we may add or drop support for particularversions of an operating system, programming language, or tooling. Seefoundational support matricesfor our supported languages.
The most recent release is always supported. Support for earlier minor versionsends when a new minor version under the same major version is released. Supportfor earlier major versions ends four quarters beyond the quarter that thebreaking release is introduced. For example, when Python 4.21.0 was released inMay of 2022, that set the end of public support of Python 3.20.1 at theend of 2023 Q2.
While not mandatory, gRPC applications often leverage Protocol Buffers forservice definitions and data serialization. Most of the example code from thissite uses version 3 of the protocol buffer language (proto3).
Check the version of protoc (as indicated below) after installation toensure that it is sufficiently recent. The versions of protoc installed bysome package managers can be quite dated.
Manually download from github.com/google/protobuf/releases the zip filecorresponding to your operating system and computer architecture(protoc---.zip), or fetch the file using commands suchas the following:
This chapter will discuss how to use Protocol Buffers with API design.To simplify developer experience and improve runtime efficiency, gRPC APIsshould use Protocol Buffers version 3 (proto3) for API definition.
Protocol Buffers is a simplelanguage-neutral and platform-neutral Interface Definition Language (IDL)for defining data structure schemas and programming interfaces. It supportsboth binary and text wire formats, and works with many different wireprotocols on different platforms.
The reason for removing these features is to make API designs simpler, morestable, and more performant. For example, it is often necessary to filter somefields before logging a message, such as removing sensitive information. Thiswould not be possible if the fields are required.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
This project hosts the Go implementation forprotocol buffers, which is alanguage-neutral, platform-neutral, extensible mechanism for serializingstructured data. The protocol buffer language is a language for specifying theschema for structured data. This schema is compiled into language specificbindings. This project provides both a tool to generate Go code for theprotocol buffer language, and also the runtime implementation to handleserialization of messages in Go. See theprotocol buffer developer guidefor more information about protocol buffers themselves.
Code generator: Theprotoc-gen-gotool is a compiler plugin to protoc, the protocol buffer compiler. Itaugments the protoc compiler so that it knows how togenerate Go specific code for a given .proto file.
Runtime library: Theprotobuf modulecontains a set of Go packages that form the runtime implementation ofprotobufs in Go. This provides the set of interfaces thatdefine what a message isand functionality to serialize message in various formats (e.g.,wire,JSON,andtext).
This project is the second major revision of the Go protocol buffer APIimplemented by thegoogle.golang.org/protobufmodule. The first major version is implemented by thegithub.com/golang/protobufmodule.
Please report any issues there with a sufficient description of the bug orfeature request. Bug reports should ideally be accompanied by a minimalreproduction of the issue. Irreproducible bugs are difficult to diagnose and fix(and likely to be closed after some period of time). Bug reports must specifythe version of theGo protocol buffer moduleand also the version of theprotocol buffer toolchainbeing used.
Users should use generated code produced by a version ofprotoc-gen-gothat is identical to the runtime version provided by theprotobuf module. Thisproject promises that the runtime remains compatible with code produced by aversion of the generator that is no older than 1 year from the version of theruntime used, according to the release dates of the minor version. Generatedcode is expected to use a runtime version that is at least as new as thegenerator used to produce it. Generated code contains references toprotoimpl.EnforceVersionto statically ensure that the generated code and runtime do not driftsufficiently far apart.
This project is the second major revision(released in 2020)of the Go protocol buffer API implemented by thegoogle.golang.org/protobufmodule. The first major version(released publicly in 2010)is implemented by thegithub.com/golang/protobufmodule.
This interface reduced the set of types that can be passed to proto.Unmarshalfrom the universal set of all possible Go types to those with a specialProtoMessage marker method. The intention of this change is to limit theprotobuf API to only operate on protobuf data types (i.e., protobuf messages).For example, there is no sensible operation if a Go channel were passed to theprotobuf API as a channel cannot be serialized. The restricted interface wouldprevent that.
This interface does not behaviorally describe what a protobuf message is, butacts as a marker with an undocumented expectation that protobuf messages must bea Go struct with a specific layout of fields with formatted tags. Thisexpectation is not statically enforced by the Go language, for it is animplementation detail checked dynamically at runtime using Go reflection. Backin 2012, the only types with this marker were those generated byprotoc-gen-go. Since protoc-gen-go would always generate messages with theproper layout of fields, this was deemed an acceptable and dramatic improvementover interface.
Over the next 10 years,use of Go would skyrocket and use ofprotobufs in Go would skyrocket as well. With increased popularity also camemore diverse usages and requirements for Go protobufs and an increased number ofcustom proto.Message implementations that were not generated byprotoc-gen-go.
Passing custom proto.Message types to the protobuf APIs: A concretemessage implementation might work with some top-level functions (e.g.,proto.Marshal), but cause others (e.g., proto.Equal) to choke and panic.This occurs because the type only had partial support for being an actualmessage by only implementing the proto.Marshaler interface or havingmalformed struct field tags that happened to work with one function, but notanother.
Using Go reflection on any proto.Message types: A common desire is towrite general-purpose code that operates on any protobuf message. Forexample, a microservice might want to populate a trace_id field if it ispresent in a message. To accomplish this, one would use Go reflection tointrospect the message type, and assume it were a pointer to a Go structwith a field named TraceId (as would be commonly produced byprotoc-gen-go). If the concrete message type did not match thisexpectation, it either failed to work or even resulted in a panic. Such wasthe case for concrete message types that might be backed by a Go map insteadof a Go struct.
ff7609af8f