chore: Add release notes for protobuf 4.x upgrade #7363
Conversation
libraries-bom/releaseNotes.md
Outdated
| @@ -0,0 +1,38 @@ | |||
| ### Upgrade Overview | |||
| The `Libraries-Bom` and its managed libraries have been upgraded to use **Protobuf v4.33.2**. All Protobuf gen code included in the managed libraries has been regenerated using `protoc v33.2`. Please note that this update necessitates a minimum Protobuf runtime of **v4.33.2**. | |||
There was a problem hiding this comment.
Perhaps we should also call out that that protobuf runtime + gen code have both been upgrade?
There was a problem hiding this comment.
Protobuf runtime was upgraded to 4.29.x last year already. So this version is specific to gen code upgrade.
libraries-bom/releaseNotes.md
Outdated
|
|
||
| --- | ||
| ### ✅ Backward Compatibility | ||
| The new protobuf-java v4.33.2 runtime is fully backward-compatible with protoc gen code 3.x. You should not experience any runtime incompatibilities from using older gen code with the new runtime. |
There was a problem hiding this comment.
nit: it says you should not experience any runtime incompatibilities and then a few sections below it says Known Incompatibilities & Mitigations: 1. Runtime Version Mismatch
Perhaps we may can reword this to be something like (just a draft message): For a majority of users, you should not experience any runtime incompatibilities. There are a few rare incompatibilities (#link-to-section-below)...
There was a problem hiding this comment.
The claim here is fully backward-compatible with protoc gen code which is still technically true. All the incompatibility below does not come from gen code vs runtime compatibility. They are breaking changes in runtime or gen code only. That being said, I agree it could be confusing since customers may not be fully aware of different types of breaking changes.
There was a problem hiding this comment.
Re-worded this sentence, hopefully its clearer.
libraries-bom/releaseNotes.md
Outdated
| * **Symptoms:** | ||
| * `java.lang.NoClassDefFoundError: com/google/protobuf/RuntimeVersion$RuntimeDomain` (when using 3.x versions). | ||
| * `com.google.protobuf.RuntimeVersion$ProtobufRuntimeVersionException` (when using older 4.x versions). | ||
| * **Mitigation:** Upgrade `protobuf-java` to **v4.33.2**. |
There was a problem hiding this comment.
qq, if they pull in the libraries-bom, this case would be if they manually override the protobuf-java version somewhere in the application, right? Would there be any other possibility?
There was a problem hiding this comment.
Yes, it would only happen if protobuf-java version is overridden in their applications.
Co-authored-by: Lawrence Qiu <[email protected]>
Co-authored-by: Lawrence Qiu <[email protected]>
| --- | ||
| ### ⚠️ Advisory: Vulnerability Warnings | ||
| After upgrading, you may see a new warning in your logs: `Vulnerable protobuf generated type in use`. | ||
| This warning does not mean the Java SDK is vulnerable. It indicates that your application, or one of its other dependencies, is still using gen code < `3.21.7`. |
There was a problem hiding this comment.
should we recommend that the customer resolve this ASAP? Since this is technically a CVE?
There was a problem hiding this comment.
I think it's better to leave it to the customer. It is a medium CVE and customers may decide to ignore it.
There was a problem hiding this comment.
Perhaps we can link to the CVE and the customer can decide the importance
libraries-bom/releaseNotes.md
Outdated
| While rare, the following incompatibilities may occur due to the version update: | ||
|
|
||
| #### 1. Runtime Version Mismatch | ||
| * **Issue:** The minimum required `protobuf-java` runtime version is now **v4.33.2**. Starting with the 4.x runtime, [validations](https://github.com/protocolbuffers/protobuf/blob/1082da2da37a0887d0cfd70abf4a00e8973cd8bf/java/core/src/main/java/com/google/protobuf/RuntimeVersion.java#L55-L73) ensure the runtime version is higher than the gen code version. Using a lower version of protobuf-java will produce errors below. |
There was a problem hiding this comment.
nit: Consider moving the symptoms to be first in each section for each of the incompatibilities. I think the user would be scanning for the specific error messages (e.g. NoClassDef or ProtobufRuntimeVersionException) that they're seeing
| * **Mitigation:** There are no direct alternative methods; it is suggested to stop using them. | ||
|
|
||
| #### 4. Legacy Generated Code (v2.x) | ||
| * **Issue:** The 4.33.x runtime is incompatible with v2.x gen code. |
There was a problem hiding this comment.
Is there a specific error message that shows up when this occurs? What would the user be looking for in the error message to know that this is the case?
There was a problem hiding this comment.
Unfortunately I don't have it. There will be different errors in different scenarios, actually for basic scenarios 4.33.x might still be compatible. Considering this is a very old use case and really hard to reproduce, I think it's OK to not mention the specific errors.
Co-authored-by: Lawrence Qiu <[email protected]>
|
v26.75.0 release notes has been updated |
3 participants
This release note is not intended to be merged, it is intended for reviewing only. I'll copy these notes to the release page directly after releasing.