From cd714d9d9adf43cc882309f616d17d2047645396 Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Thu, 29 Apr 2021 09:15:04 -0700 Subject: [PATCH 1/7] P5: Require a gRFC for large scale changes to gRPC core --- P5-core-large-scale-changes.md | 57 ++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 P5-core-large-scale-changes.md diff --git a/P5-core-large-scale-changes.md b/P5-core-large-scale-changes.md new file mode 100644 index 000000000..212a544b7 --- /dev/null +++ b/P5-core-large-scale-changes.md @@ -0,0 +1,57 @@ +Title +---- +* Author(s): ctiller@google.com (Craig Tiller) +* Approver: a11r +* Status: Draft +* Implemented in: N/A +* Last updated: 4/29/2021 +* Discussion at: (filled after thread exists) + +## Abstract + +Assert that gRFC's are needed before large scale changes to gRPC Core are undertaken. + +## Background + +The gRFC process was intended to (quoting from README.md in this repository): +* Provide increased visibility to the community on upcoming changes and the design considerations around them. +* Provide the 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. + +There are now multiple teams contributing to gRPC Core, each with different motivations and organizational aims. +These teams form a community that needs to find consensus on overall direction of the gRPC core codebase. +As such, the core API should no longer be considered a cut point for gRFC's, and instead any larger change ought to be considered for such a process. + +### Related Proposals: +* This change extends P3 to expect gRFC's for changes to gRPC Cores internals and not just it's public API. + +## Proposal + +Any large scale change to gRPC Core should not be implemented without following the gRFC process. + +A large scale change is one that has a wide-ranging impact on the implementation of gRPC Core. + +Such changes include: +* Changes to extensibility points, or the types used by extensibility points. +* Changes that require downstream consumers of gRPC Core to modify their code. +* Changes with a significant performance impact. +* Changes to vocabulary types - types that are used broadly within the library. +* Changes that constrain future development. +* Changes that modify system architecture. + +## Rationale + +This gRFC will slow down progress on some kinds of changes for gRPC Core. +At this point in gRPC's lifetime this is probably appropriate: gRPC is a widely used product, multiple teams contribute to it's development, and any single person cannot cover all of the impact of changes on the myriad use cases for which gRPC is deployed. + +By moving the design process to written discussion we lessen the need for meetings. +This helps us include more voices in the design process - people who may not work at Google, or may be intimidated to speak up in large groups. +By identifying design problems before they reach downstream overall project velocity will likely increase. + +## Implementation + +N/A + +## Open issues (if applicable) + +N/A From a3a11f9e00ac803a8efa5bf1f445c86ae6b8efa0 Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Thu, 29 Apr 2021 14:40:07 -0700 Subject: [PATCH 2/7] Add discussion list --- P5-core-large-scale-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/P5-core-large-scale-changes.md b/P5-core-large-scale-changes.md index 212a544b7..f0587ad5e 100644 --- a/P5-core-large-scale-changes.md +++ b/P5-core-large-scale-changes.md @@ -5,7 +5,7 @@ Title * Status: Draft * Implemented in: N/A * Last updated: 4/29/2021 -* Discussion at: (filled after thread exists) +* Discussion at: https://groups.google.com/g/grpc-io/c/q11WFj3KQOs ## Abstract From 5b64c30e3639c676bee8fbaea25b465f798ff035 Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Fri, 30 Apr 2021 08:20:54 -0700 Subject: [PATCH 3/7] Review feedback - fix grammar Co-authored-by: Christopher Warrington --- P5-core-large-scale-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/P5-core-large-scale-changes.md b/P5-core-large-scale-changes.md index f0587ad5e..a72614f5b 100644 --- a/P5-core-large-scale-changes.md +++ b/P5-core-large-scale-changes.md @@ -42,7 +42,7 @@ Such changes include: ## Rationale This gRFC will slow down progress on some kinds of changes for gRPC Core. -At this point in gRPC's lifetime this is probably appropriate: gRPC is a widely used product, multiple teams contribute to it's development, and any single person cannot cover all of the impact of changes on the myriad use cases for which gRPC is deployed. +At this point in gRPC's lifetime this is probably appropriate: gRPC is a widely used product, multiple teams contribute to its development, and any single person cannot cover all of the impact of changes on the myriad use cases for which gRPC is deployed. By moving the design process to written discussion we lessen the need for meetings. This helps us include more voices in the design process - people who may not work at Google, or may be intimidated to speak up in large groups. From 6f8333a77697685b035646b6f64cf2f9ced4fbed Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Fri, 30 Apr 2021 08:21:00 -0700 Subject: [PATCH 4/7] Review feedback - fix grammar Co-authored-by: Christopher Warrington --- P5-core-large-scale-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/P5-core-large-scale-changes.md b/P5-core-large-scale-changes.md index a72614f5b..de444e1a7 100644 --- a/P5-core-large-scale-changes.md +++ b/P5-core-large-scale-changes.md @@ -23,7 +23,7 @@ These teams form a community that needs to find consensus on overall direction o As such, the core API should no longer be considered a cut point for gRFC's, and instead any larger change ought to be considered for such a process. ### Related Proposals: -* This change extends P3 to expect gRFC's for changes to gRPC Cores internals and not just it's public API. +* This change extends P3 to expect gRFC's for changes to gRPC Core's internals and not just its public API. ## Proposal From 89b6e59fe3959704590263947fe6469a356b022c Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Thu, 6 May 2021 08:52:28 -0700 Subject: [PATCH 5/7] Include a lightweight update period for LSC's --- P5-core-large-scale-changes.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/P5-core-large-scale-changes.md b/P5-core-large-scale-changes.md index de444e1a7..ca4f215f4 100644 --- a/P5-core-large-scale-changes.md +++ b/P5-core-large-scale-changes.md @@ -39,6 +39,12 @@ Such changes include: * Changes that constrain future development. * Changes that modify system architecture. +Since implementation experience can affect how a large scale change may proceed, it's additionally proposed that LSC gRFC's may be updated by later PR's against the approved change. +Such updates would be subject to a minimum five business day approval process, rather than the usual ten as it's assumed that stake holders would already be identified and have sufficient context. +Updates to LSC gRFC's must add or extend a final section 'Change Log' with a summary of what has changed from version to version of the gRFC. + +Finally, since the five day period has been somewhat arbitrarily chosen, as has what is included and excluded - this gRFC may be updated with the same process as for LSC's. + ## Rationale This gRFC will slow down progress on some kinds of changes for gRPC Core. From 3be0d707882d5c958bcff396514b575744faa36a Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Thu, 13 May 2021 14:49:49 -0700 Subject: [PATCH 6/7] Review feedback --- P5-core-large-scale-changes.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/P5-core-large-scale-changes.md b/P5-core-large-scale-changes.md index ca4f215f4..33cf45f8b 100644 --- a/P5-core-large-scale-changes.md +++ b/P5-core-large-scale-changes.md @@ -9,7 +9,7 @@ Title ## Abstract -Assert that gRFC's are needed before large scale changes to gRPC Core are undertaken. +Assert that gRFCs are needed before large scale changes to gRPC Core are undertaken. ## Background @@ -20,10 +20,10 @@ The gRFC process was intended to (quoting from README.md in this repository): There are now multiple teams contributing to gRPC Core, each with different motivations and organizational aims. These teams form a community that needs to find consensus on overall direction of the gRPC core codebase. -As such, the core API should no longer be considered a cut point for gRFC's, and instead any larger change ought to be considered for such a process. +As such, the core API should no longer be considered a cut point for gRFCs, and instead any larger change ought to be considered for such a process. ### Related Proposals: -* This change extends P3 to expect gRFC's for changes to gRPC Core's internals and not just its public API. +* This change extends [P3](https://github.com/grpc/proposal/blob/master/P3-grfcs-for-core-api-changes.md) to expect gRFCs for changes to gRPC Core's internals and not just its public API. ## Proposal @@ -39,9 +39,9 @@ Such changes include: * Changes that constrain future development. * Changes that modify system architecture. -Since implementation experience can affect how a large scale change may proceed, it's additionally proposed that LSC gRFC's may be updated by later PR's against the approved change. +Since implementation experience can affect how a large scale change may proceed, it's additionally proposed that LSC gRFCs may be updated by later PR's against the approved change. Such updates would be subject to a minimum five business day approval process, rather than the usual ten as it's assumed that stake holders would already be identified and have sufficient context. -Updates to LSC gRFC's must add or extend a final section 'Change Log' with a summary of what has changed from version to version of the gRFC. +Updates to LSC gRFCs must add or extend a final section 'Change Log' with a summary of what has changed from version to version of the gRFC. Finally, since the five day period has been somewhat arbitrarily chosen, as has what is included and excluded - this gRFC may be updated with the same process as for LSC's. From e2bc712c71d166bdd1ea2d5e51ace4daa0789749 Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Thu, 13 May 2021 14:54:48 -0700 Subject: [PATCH 7/7] Further review feedback --- P5-core-large-scale-changes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/P5-core-large-scale-changes.md b/P5-core-large-scale-changes.md index 33cf45f8b..8758a48d2 100644 --- a/P5-core-large-scale-changes.md +++ b/P5-core-large-scale-changes.md @@ -33,11 +33,10 @@ A large scale change is one that has a wide-ranging impact on the implementation Such changes include: * Changes to extensibility points, or the types used by extensibility points. -* Changes that require downstream consumers of gRPC Core to modify their code. * Changes with a significant performance impact. * Changes to vocabulary types - types that are used broadly within the library. -* Changes that constrain future development. -* Changes that modify system architecture. +* Changes that constrain future development, e.g. changes that they would likely need a large scale change to undo. +* Changes that modify basic assumptions - where memory is coming from, implied lock orderings across components. Since implementation experience can affect how a large scale change may proceed, it's additionally proposed that LSC gRFCs may be updated by later PR's against the approved change. Such updates would be subject to a minimum five business day approval process, rather than the usual ten as it's assumed that stake holders would already be identified and have sufficient context.