Cross-Version Runtime Guarantee

The guarantees that the language has for cross-version runtime compatibility.

Protobuf language bindings have two components. The generated code (typically produced from protoc) and the runtime libraries that must be included when using the generated code. When these come from different releases of protobuf, we are in a “cross version runtime” situation.

Historically, protobuf has not documented its cross-version runtime compatibility guarantees and has been inconsistent about enforcing what guarantees it provides. Moving forward, we intend to offer the following guarantees across all languages except C++. These are the default guarantees; however, owners of protobuf code generators and runtimes may explicitly override them with more specific guarantees for that language.

Major Versions

Protobuf will not support mixing generated code and runtimes across major version boundaries. We will add “poison pills” where possible to detect these mismatches.

Minor Versions

Within a single major runtime version, generated code from an older version of protoc will run on a newer runtime.

Within a single major runtime version, generated code from a newer version of protoc is not guaranteed to run on an older runtime. We will add “poison pills” where possible to detect these mismatches.

Security Exception

We reserve the right to violate the above promises if needed for security reasons. We expect these exceptions to be rare, but will always prioritize security above these guarantees. For example, footmitten required paired updates to both the runtime and the generated code for Java. As a result, code generated by 3.20.3 (which contained the footmitten fix) would not load with runtime library 3.21.6 (which predates the footmitten fix), creating the following compatibility matrix:

		Generated Code Version
		3.20.2	3.20.3	3.21.6	3.21.7
Runtime Version	3.20.2	Vuln	Broken	Vuln	Broken
	3.20.3	Vuln	Works	Vuln	Works?
	3.21.6	Vuln	Broken	Vuln	Broken
	3.21.7	Vuln	Works	Vuln	Works

“Vuln” indicates that the combination will successfully start, but the security vulnerability still exists.
“Works” indicates that the combination will successfully start and does not have the vulnerability.
“Broken” indicates that the combination will not successfully start.
Bold indicates configurations that were never deliberately intended to function together given the guarantees outlined in this topic.

No Coexistence of Multiple Major Runtime Versions

Coexistence of multiple major versions in the same process is not supported.

C++ Specific Guarantees

Protobuf C++ disclaims all cross-runtime support and requires an exact match between its generated code version and its runtime version at all times. Additionally, Protobuf C++ makes no guarantees about ABI stability across any releases (major, minor, or micro).