docs: add RPC deprecation policy#10878
Conversation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request establishes a standardized deprecation policy for the project's RPC interface. By defining a clear, multi-stage lifecycle for deprecating and removing fields and methods, the changes aim to improve backward compatibility and prevent silent behavior changes for clients using older protobuf definitions. Highlights
New Features🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
🟢 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. |
1 participant
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