From 75174c2b1efc4ffc530ecac990cd28e9a1467074 Mon Sep 17 00:00:00 2001 From: ematejska Date: Thu, 7 Jan 2021 11:20:19 -0800 Subject: [PATCH 1/6] Initial proposed updates to the RFC template --- rfcs/yyyymmdd-rfc-template.md | 85 +++++++++++++++-------------------- 1 file changed, 37 insertions(+), 48 deletions(-) diff --git a/rfcs/yyyymmdd-rfc-template.md b/rfcs/yyyymmdd-rfc-template.md index ca386f181..8e497111f 100644 --- a/rfcs/yyyymmdd-rfc-template.md +++ b/rfcs/yyyymmdd-rfc-template.md @@ -2,10 +2,8 @@ | Status | (Proposed / Accepted / Implemented / Obsolete) | :-------------- |:---------------------------------------------------- | -| **RFC #** | [NNN](https://github.com/tensorflow/community/pull/NNN) (update when you have community PR #)| | **Author(s)** | My Name (me@example.org), AN Other (you@example.org) | | **Sponsor** | A N Expert (whomever@tensorflow.org) | -| **Updated** | YYYY-MM-DD | | **Obsoletes** | TF-RFC it replaces, else remove this header | ## Objective @@ -18,56 +16,39 @@ non-goals? This is your executive summary; keep it short, elaborate below. Why this is a valuable problem to solve? What background information is needed to show how this design addresses the problem? -Which users are affected by the problem? Why is it a problem? What data supports -this? What related work exists? - -## User Benefit - How will users (or other contributors) benefit from this work? What would be the -headline in the release notes or blog post? - -## Design Proposal - -This is the meat of the document, where you explain your proposal. If you have -multiple alternatives, be sure to use sub-sections for better separation of the -idea, and list pros/cons to each approach. If there are alternatives that you -have eliminated, you should also list those here, and explain why you believe -your chosen approach is superior. +headline in the release notes or blog post? What data supports +this? What related work exists? -Make sure you’ve thought through and addressed the following sections. If a section is not relevant to your specific proposal, please explain why, e.g. your RFC addresses a convention or process, not an API. +## Proposed Solution +Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds (if there are any). +## Detailed Design -### Alternatives Considered -* Make sure to discuss the relative merits of alternatives to your proposal. +Describe the design of the solution in detail. If it's a new API, show the full API and its documentation comments detailing what it does. The detail in this section should be sufficient for someone who is not one of the authors to be able to reasonably implement the feature. -### Performance Implications -* Do you expect any (speed / memory)? How will you confirm? -* There should be microbenchmarks. Are there? -* There should be end-to-end tests and benchmarks. If there are not (since this is still a design), how will you track that these will be created? +* If design changes existing API or creates new ones, the design owner should create end-to-end examples (ideally, a tutorial) which reflects how new feature will be used. Some things to consider related to the tutorial: + - The minimum requirements for this are to consider how this would be used in a Keras-based workflow, as well as a non-Keras (low-level) workflow. If either isn’t applicable, explain why. + - It should show the usage of the new feature in an end to end example (from data reading to serving, if applicable). Many new features have unexpected effects in parts far away from the place of change that can be found by running through an end-to-end example. TFX [Examples](https://github.com/tensorflow/tfx/tree/master/tfx/examples) have historically been good in identifying such unexpected side-effects and are as such one recommended path for testing things end-to-end. + - This should be written as if it is documentation of the new feature, i.e., consumable by a user, not a TensorFlow developer. + - The code does not need to work (since the feature is not implemented yet) but the expectation is that the code does work before the feature can be merged. -### Dependencies -* Dependencies: does this proposal add any new dependencies to TensorFlow? -* Dependent projects: are there other areas of TensorFlow or things that use TensorFlow (TFX/pipelines, TensorBoard, etc.) that this affects? How have you identified these dependencies and are you sure they are complete? If there are dependencies, how are you managing those changes? +## User Impact +What are the user-facing changes? How will this feature be rolled out? -### Engineering Impact +## Engineering Impact +Please answer the following: * Do you expect changes to binary size / startup time / build time / test times? * Who will maintain this code? Is this code in its own buildable unit? Can this code be tested in its own? Is visibility suitably restricted to only a small API surface for others to use? -### Platforms and Environments -* Platforms: does this work on all platforms supported by TensorFlow? If not, why is that ok? Will it work on embedded/mobile? Does it impact automatic code generation or mobile stripping tooling? Will it work with transformation tools? -* Execution environments (Cloud services, accelerator hardware): what impact do you expect and how will you confirm? - -### Best Practices -* Does this proposal change best practices for some aspect of using/developing TensorFlow? How will these changes be communicated/enforced? - -### Tutorials and Examples -* If design changes existing API or creates new ones, the design owner should create end-to-end examples (ideally, a tutorial) which reflects how new feature will be used. Some things to consider related to the tutorial: - - The minimum requirements for this are to consider how this would be used in a Keras-based workflow, as well as a non-Keras (low-level) workflow. If either isn’t applicable, explain why. - - It should show the usage of the new feature in an end to end example (from data reading to serving, if applicable). Many new features have unexpected effects in parts far away from the place of change that can be found by running through an end-to-end example. TFX [Examples](https://github.com/tensorflow/tfx/tree/master/tfx/examples) have historically been good in identifying such unexpected side-effects and are as such one recommended path for testing things end-to-end. - - This should be written as if it is documentation of the new feature, i.e., consumable by a user, not a TensorFlow developer. - - The code does not need to work (since the feature is not implemented yet) but the expectation is that the code does work before the feature can be merged. +## Performance Implications +Please answer the following: +* Do you expect any changes to performance (speed / memory)? How will you confirm? +* There should be microbenchmarks. Are there? +* There should be end-to-end tests and benchmarks. If there are not (since this is still a design), how will you track that these will be created? -### Compatibility +## Compatibility +Please answer the following: * Does the design conform to the backwards & forwards compatibility [requirements](https://www.tensorflow.org/programmers_guide/version_compat)? * How will this proposal interact with other parts of the TensorFlow Ecosystem? - How will it work with TFLite? @@ -76,15 +57,23 @@ Make sure you’ve thought through and addressed the following sections. If a se - Will this work on GPU/TPU? - How will it serialize to a SavedModel? -### User Impact -* What are the user-facing changes? How will this feature be rolled out? +## Dependencies +Does this proposal add any new dependencies to TensorFlow? Are there other areas of TensorFlow or things that use TensorFlow (TFX/pipelines, TensorBoard, etc.) that this affects? How have you identified these dependencies and are you sure they are complete? If there are dependencies, how are you managing those changes? -## Detailed Design +## Platforms and Environments +Please answer the following: +* Platforms: does this work on all platforms supported by TensorFlow? If not, why is that ok? Will it work on embedded/mobile? Does it impact automatic code generation or mobile stripping tooling? Will it work with transformation tools? +* Execution environments (Cloud services, accelerator hardware): what impact do you expect and how will you confirm? -This section is optional. Elaborate on details if they’re important to -understanding the design, but would make it hard to read the proposal section -above. +## Best Practices +Does this proposal change best practices for some aspect of using/developing TensorFlow? How will these changes be communicated/enforced? -## Questions and Discussion Topics +## Tutorials, Examples and Documentation +What is the plan for documentation? + +## Alternatives +If there are alternatives that you have eliminated, you should also list those here, and explain why you believe +your chosen approach is superior. List pros/cons to each approach. +## Questions and Discussion Topics Seed this with open questions you require feedback on from the RFC process. From d0fcfcd89d093dbde6d8579a1d725bf1053ebe08 Mon Sep 17 00:00:00 2001 From: ematejska Date: Thu, 7 Jan 2021 11:54:25 -0800 Subject: [PATCH 2/6] Updating the template to clarify API Design notes --- rfcs/yyyymmdd-rfc-template.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/rfcs/yyyymmdd-rfc-template.md b/rfcs/yyyymmdd-rfc-template.md index 8e497111f..9d6095f73 100644 --- a/rfcs/yyyymmdd-rfc-template.md +++ b/rfcs/yyyymmdd-rfc-template.md @@ -25,30 +25,29 @@ Describe your solution to the problem. Provide examples and describe how they wo ## Detailed Design -Describe the design of the solution in detail. If it's a new API, show the full API and its documentation comments detailing what it does. The detail in this section should be sufficient for someone who is not one of the authors to be able to reasonably implement the feature. +Describe the design of the solution in detail. The detail in this section should be sufficient for someone who is not one of the authors to be able to reasonably implement the feature. -* If design changes existing API or creates new ones, the design owner should create end-to-end examples (ideally, a tutorial) which reflects how new feature will be used. Some things to consider related to the tutorial: - - The minimum requirements for this are to consider how this would be used in a Keras-based workflow, as well as a non-Keras (low-level) workflow. If either isn’t applicable, explain why. - - It should show the usage of the new feature in an end to end example (from data reading to serving, if applicable). Many new features have unexpected effects in parts far away from the place of change that can be found by running through an end-to-end example. TFX [Examples](https://github.com/tensorflow/tfx/tree/master/tfx/examples) have historically been good in identifying such unexpected side-effects and are as such one recommended path for testing things end-to-end. - - This should be written as if it is documentation of the new feature, i.e., consumable by a user, not a TensorFlow developer. - - The code does not need to work (since the feature is not implemented yet) but the expectation is that the code does work before the feature can be merged. +If the design affects API (new, changed, removed, upgraded from experimental), please describe the changes in detail. Here is more [information](https://github.com/tensorflow/community/blob/master/governance/api-reviews.md) about what API owners are looking for. + +For new changed API, show the full API and its documentation comments detailing what it does along with end-to-end examples (ideally, a tutorial) showing it's use. +* The minimum requirements for this are to consider how this would be used in a Keras-based workflow, as well as a non-Keras (low-level) workflow. If either isn’t applicable, explain why. +* It should show the usage of the new feature in an end to end example (from data reading to serving, if applicable). Many new features have unexpected effects in parts far away from the place of change that can be found by running through an end-to-end example. TFX [Examples](https://github.com/tensorflow/tfx/tree/master/tfx/examples) have historically been good in identifying such unexpected side-effects and are as such one recommended path for testing things end-to-end. +* This should be written as if it is documentation of the new feature, i.e., consumable by a user, not a TensorFlow developer. +* The code does not need to work (since the feature is not implemented yet) but the expectation is that the code does work before the feature can be merged. ## User Impact What are the user-facing changes? How will this feature be rolled out? ## Engineering Impact -Please answer the following: * Do you expect changes to binary size / startup time / build time / test times? * Who will maintain this code? Is this code in its own buildable unit? Can this code be tested in its own? Is visibility suitably restricted to only a small API surface for others to use? ## Performance Implications -Please answer the following: * Do you expect any changes to performance (speed / memory)? How will you confirm? * There should be microbenchmarks. Are there? * There should be end-to-end tests and benchmarks. If there are not (since this is still a design), how will you track that these will be created? ## Compatibility -Please answer the following: * Does the design conform to the backwards & forwards compatibility [requirements](https://www.tensorflow.org/programmers_guide/version_compat)? * How will this proposal interact with other parts of the TensorFlow Ecosystem? - How will it work with TFLite? @@ -61,7 +60,6 @@ Please answer the following: Does this proposal add any new dependencies to TensorFlow? Are there other areas of TensorFlow or things that use TensorFlow (TFX/pipelines, TensorBoard, etc.) that this affects? How have you identified these dependencies and are you sure they are complete? If there are dependencies, how are you managing those changes? ## Platforms and Environments -Please answer the following: * Platforms: does this work on all platforms supported by TensorFlow? If not, why is that ok? Will it work on embedded/mobile? Does it impact automatic code generation or mobile stripping tooling? Will it work with transformation tools? * Execution environments (Cloud services, accelerator hardware): what impact do you expect and how will you confirm? From a66328dbdbc356e6a6fe734be0e5c408f66e79db Mon Sep 17 00:00:00 2001 From: ematejska Date: Thu, 7 Jan 2021 15:40:07 -0800 Subject: [PATCH 3/6] Updating to save a spot for the design review notes --- rfcs/yyyymmdd-rfc-template.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/rfcs/yyyymmdd-rfc-template.md b/rfcs/yyyymmdd-rfc-template.md index 9d6095f73..787432d7f 100644 --- a/rfcs/yyyymmdd-rfc-template.md +++ b/rfcs/yyyymmdd-rfc-template.md @@ -75,3 +75,6 @@ your chosen approach is superior. List pros/cons to each approach. ## Questions and Discussion Topics Seed this with open questions you require feedback on from the RFC process. + +## Design Review Notes +Please post the notes from the Design Review here. From 0e0a1105c36bbcf76d3af1668576174483f6bd67 Mon Sep 17 00:00:00 2001 From: ematejska Date: Fri, 8 Jan 2021 14:40:14 -0800 Subject: [PATCH 4/6] Small grammar fixes --- rfcs/yyyymmdd-rfc-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/yyyymmdd-rfc-template.md b/rfcs/yyyymmdd-rfc-template.md index 787432d7f..059eb839f 100644 --- a/rfcs/yyyymmdd-rfc-template.md +++ b/rfcs/yyyymmdd-rfc-template.md @@ -29,7 +29,7 @@ Describe the design of the solution in detail. The detail in this section should If the design affects API (new, changed, removed, upgraded from experimental), please describe the changes in detail. Here is more [information](https://github.com/tensorflow/community/blob/master/governance/api-reviews.md) about what API owners are looking for. -For new changed API, show the full API and its documentation comments detailing what it does along with end-to-end examples (ideally, a tutorial) showing it's use. +For new or changed API, show the full API and its documentation comments detailing what it does along with end-to-end examples (ideally, a tutorial) showing its use. * The minimum requirements for this are to consider how this would be used in a Keras-based workflow, as well as a non-Keras (low-level) workflow. If either isn’t applicable, explain why. * It should show the usage of the new feature in an end to end example (from data reading to serving, if applicable). Many new features have unexpected effects in parts far away from the place of change that can be found by running through an end-to-end example. TFX [Examples](https://github.com/tensorflow/tfx/tree/master/tfx/examples) have historically been good in identifying such unexpected side-effects and are as such one recommended path for testing things end-to-end. * This should be written as if it is documentation of the new feature, i.e., consumable by a user, not a TensorFlow developer. From 7be1166ed5d0b46c602f74900ab37e49f30ac3b8 Mon Sep 17 00:00:00 2001 From: ematejska Date: Thu, 18 Feb 2021 11:42:45 -0800 Subject: [PATCH 5/6] Updating the API design section. --- rfcs/yyyymmdd-rfc-template.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/rfcs/yyyymmdd-rfc-template.md b/rfcs/yyyymmdd-rfc-template.md index 059eb839f..33fb3ed24 100644 --- a/rfcs/yyyymmdd-rfc-template.md +++ b/rfcs/yyyymmdd-rfc-template.md @@ -29,11 +29,7 @@ Describe the design of the solution in detail. The detail in this section should If the design affects API (new, changed, removed, upgraded from experimental), please describe the changes in detail. Here is more [information](https://github.com/tensorflow/community/blob/master/governance/api-reviews.md) about what API owners are looking for. -For new or changed API, show the full API and its documentation comments detailing what it does along with end-to-end examples (ideally, a tutorial) showing its use. -* The minimum requirements for this are to consider how this would be used in a Keras-based workflow, as well as a non-Keras (low-level) workflow. If either isn’t applicable, explain why. -* It should show the usage of the new feature in an end to end example (from data reading to serving, if applicable). Many new features have unexpected effects in parts far away from the place of change that can be found by running through an end-to-end example. TFX [Examples](https://github.com/tensorflow/tfx/tree/master/tfx/examples) have historically been good in identifying such unexpected side-effects and are as such one recommended path for testing things end-to-end. -* This should be written as if it is documentation of the new feature, i.e., consumable by a user, not a TensorFlow developer. -* The code does not need to work (since the feature is not implemented yet) but the expectation is that the code does work before the feature can be merged. +For new or changed API, show the full API and its [documentation comments](https://github.com/tensorflow/community/blob/master/governance/api-reviews.md#docstrings) detailing what it does. Please think of running through an end-to-end example. TFX [Examples](https://github.com/tensorflow/tfx/tree/master/tfx/examples) have historically been good in identifying unexpected end-to-end side-effects and are as such one recommended path for testing things end-to-end. ## User Impact What are the user-facing changes? How will this feature be rolled out? From e446dfb340c41fab10579d78bb92090538322277 Mon Sep 17 00:00:00 2001 From: ematejska Date: Thu, 18 Feb 2021 11:49:04 -0800 Subject: [PATCH 6/6] Fixing some grammar --- rfcs/yyyymmdd-rfc-template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/yyyymmdd-rfc-template.md b/rfcs/yyyymmdd-rfc-template.md index 33fb3ed24..6ba4c2987 100644 --- a/rfcs/yyyymmdd-rfc-template.md +++ b/rfcs/yyyymmdd-rfc-template.md @@ -8,12 +8,12 @@ ## Objective -What are we doing and why? What problem will this solve? What are the goals and +What are you doing and why? What problem will this solve? What are the goals and non-goals? This is your executive summary; keep it short, elaborate below. ## Motivation -Why this is a valuable problem to solve? What background information is needed +Why it this a valuable problem to solve? What background information is needed to show how this design addresses the problem? How will users (or other contributors) benefit from this work? What would be the