docs: add RPC deprecation policy#10878
Conversation
🟢 PR Severity: LOW
🟢 Low (2 files)
AnalysisBoth changed files are in the To override, add a |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive RPC Deprecation Policy document (docs/rpc_deprecation_policy.md) and updates the development guidelines to reference it. The policy outlines a structured four-stage lifecycle for deprecating, rejecting, and removing behavior-affecting RPC fields and methods. The review feedback recommends valuable enhancements to the policy, including logging warnings when deprecated fields are used, clarifying the rejection behavior for proto3 primitive fields lacking explicit presence tracking, and specifying standard gRPC status codes for rejected methods.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| If the old and new fields have equivalent semantics, the server may continue | ||
| accepting the deprecated field and translating it to the new behavior during | ||
| this stage. |
There was a problem hiding this comment.
During the deprecation and announcement stages (Major N and N+1), it is highly recommended to log a warning (e.g., at warn or info level) on the server when a client sends a deprecated field. This gives node operators visibility into which of their integrated applications or scripts are still using deprecated APIs before they are hard-rejected in Major N+2.
| If the old and new fields have equivalent semantics, the server may continue | |
| accepting the deprecated field and translating it to the new behavior during | |
| this stage. | |
| If the old and new fields have equivalent semantics, the server may continue | |
| accepting the deprecated field and translating it to the new behavior during | |
| this stage. It is also recommended to log a warning when the deprecated field | |
| is used, giving operators visibility before rejection begins. |
| Keep the deprecated field in the protobuf schema, but stop honoring it. If | ||
| the client sets the field to a non-default value, return a clear | ||
| `InvalidArgument` error that identifies the deprecated field and names the | ||
| replacement field. |
There was a problem hiding this comment.
For primitive proto3 fields without explicit presence tracking (i.e., those not marked optional), the server cannot distinguish between a client explicitly setting the field to its default value (e.g., 0, false, "") and not setting it at all. Clarifying how presence tracking affects rejection behavior will help developers implement this policy correctly.
| Keep the deprecated field in the protobuf schema, but stop honoring it. If | |
| the client sets the field to a non-default value, return a clear | |
| `InvalidArgument` error that identifies the deprecated field and names the | |
| replacement field. | |
| Keep the deprecated field in the protobuf schema, but stop honoring it. If | |
| the client sets the field to a non-default value (or if presence is detected | |
| for `optional` fields), return a clear `InvalidArgument` error that identifies | |
| the deprecated field and names the replacement field. |
| 3. Prefer returning a clear error for one major release if the method can remain | ||
| registered without creating confusing behavior. The error should identify | ||
| the deprecated RPC method and name the replacement RPC method. |
There was a problem hiding this comment.
To ensure consistency across the API, it would be helpful to specify the recommended gRPC status code to return when a deprecated method is rejected (e.g., codes.Unimplemented or codes.FailedPrecondition).
| 3. Prefer returning a clear error for one major release if the method can remain | |
| registered without creating confusing behavior. The error should identify | |
| the deprecated RPC method and name the replacement RPC method. | |
| 3. Prefer returning a clear error (using `codes.Unimplemented` or `codes.FailedPrecondition`) | |
| for one major release if the method can remain registered without creating | |
| confusing behavior. The error should identify the deprecated RPC method and | |
| name the replacement RPC method. |
2 participants
Change Description
Add a RPC deprecation policy that documents the staged lifecycle for deprecating, rejecting, and finally removing public RPC fields and methods.
The policy focuses on behavior-affecting request fields, where removing a protobuf field directly can cause old gRPC clients to have values decoded as unknown fields and silently ignored.
Steps to Test
Doc-only change.
git diff --check