gRPC RFCs

Introduction

Please read the gRPC organization's governance rules and contribution guidelines before proceeding.

This repo contains the design proposals for substantial feature changes for gRPC that need to be designed upfront. The goal of the upfront design process is to:

• Provide increased visibility to the community on upcoming changes and the design considerations around them.
• Provide ability to reason about larger “sets” of changes that are too big to be covered either in an Issue or in a PR.
• Establish a consistent process for structured participation by the community on large changes, especially those that impact multiple runtimes and implementations.

Prerequisites

This process needs to be followed for any significant change to gRPC that needs design. Changes that are considered significant can be:

• Features that need implementation across runtimes and languages.
• Process changes that affect how the gRPC product is implemented.
• Breaking changes to the public API (i.e. semver major changes).

Process

1. Fork the repo and copy the template GRFC-TEMPLATE.md.
2. Rename it to $CategoryName-$Summary, eg.: A6-client-retries.md (see
   category definitions below)
   • For language-specific proposals, include the name of the language:
     L##-$Language-$Summary. Canonical names: core, cpp, csharp, go,
     java, node, objc, php, python, ruby.
3. Write up the RFC.
4. Submit a Pull Request.
5. Someone from gRPC team will be assigned as an APPROVER as part of this
   review. Once the APPROVER is assigned, the OWNER needs to start a discussion on
   grpc-io and update the PR
   with the discussion link. After this is done, the OWNER should update the gRFC
   to the state of In Review. It is expected that the APPROVER will help the
   OWNER along this process as needed.
6. For at least a period of 10 business days (the minimum comment period),
   it is expected that the OWNER will respond to the comments and make updates
   to the RFC as new commits to the PR. Through the process, the discussion
   needs to be kept to the designated thread in the mailing list in order to
   avoid splintering conversations. The OWNER is encouraged to solicit as much
   feedback on the proposal as possible during this period.
   PR comments should be limited to formatting and vocabulary.
7. If there is consensus as deemed by the APPROVER during the comment period,
   the APPROVER will mark the proposal as final and assign it a gRFC number.
   Once this is assigned (as part of the closure of discussion), the OWNER will
   update the state of the PR as final and submit the PR.
   Commits must not be squashed; the commit history serves as a log of changes
   made to the proposal.

APPROVER

• By default a11r is the approver unless another approver is assigned
  on a per-proposal basis.
• If the assigned APPROVER and the OWNER cannot satisfactorily settle an issue,
  the final APPROVER is still a11r.

Proposal Categories

The proposals shall be numbered in increasing order.

• #An - Affects all languages.
• #Pnn - Affects processes, such as the proposal process itself.
• #Lnnn - Language specific changes to external APIs or platform support.
• #Gnnnn - Protocol level changes.

Proposal Status

1. Every uncommitted proposal candidate starts off in the Draft state.
2. After it accepted for review and posted to the group, it enters the
   In Review state.
3. Once it is approved for submission by the arbiter, it goes into the
   Final state. Only minor changes are allowed (what qualifies as minor is
   left to the APPROVER).
4. If a proposal needs to be revisited, it can be moved back to the Draft
   or In Review state. This can happen if issues are discovered during
   implementation. At which point, the review process as described above must be
   followed.
5. Once a proposal is Final and if it has been implemented by a language,
   it can be updated to a status of Implemented with the implementing
   languages listed. (Listing versions is not required.)