Skip to content

Proposed updates to the RFC template #343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 6 commits into
base: master
Choose a base branch
from
Draft

Proposed updates to the RFC template #343

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
75174c2
Initial proposed updates to the RFC template
Jan 7, 2021
d0fcfcd
Updating the template to clarify API Design notes
Jan 7, 2021
a66328d
Updating to save a spot for the design review notes
Jan 7, 2021
0e0a110
Small grammar fixes
Jan 8, 2021
7be1166
Updating the API design section.
Feb 18, 2021
e446dfb
Fixing some grammar
Feb 18, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 35 additions & 49 deletions rfcs/yyyymmdd-rfc-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,72 +2,48 @@

| Status | (Proposed / Accepted / Implemented / Obsolete) |
:-------------- |:---------------------------------------------------- |
| **RFC #** | [NNN](https://github.com/tensorflow/community/pull/NNN) (update when you have community PR #)|
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The number header was added relatively recently to help people feel comfortable with referring to RFCs by number if they wished. It would be good to heart from the developer community if they still care about being able to do this.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I'll check.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In practice, nobody has been using this.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do feel like it could be pretty straightforward to refer to an RFC number as you would an issue or PR number without it being explicitly numbered here. I find myself updating this field for all submitted RFCs, so in the name of reducing busywork I'm pro dropping it.

@bhack any thoughts here?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that it is quite useful to have a reference to the PR to retrieve the context, the review comments and original related discussions to the RFC. These are available only in the PR after the RFC is merged.
But if it cannot be managed/updated and generally the RFC is not updated with subsequent PRs it could be quite easy to find the original PR on github.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

git/github history would also show at what PR it was merged, although it would require a few more clicks

| **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

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?

Which users are affected by the problem? Why is it a problem? What data supports
How will users (or other contributors) benefit from this work? What would be the
headline in the release notes or blog post? 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?
## 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).

## Design Proposal
## Detailed Design

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.
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.

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.
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](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.

### Alternatives Considered
* Make sure to discuss the relative merits of alternatives to your proposal.
## User Impact
What are the user-facing changes? How will this feature be rolled out?

### 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?

### 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?

### Engineering Impact
## Engineering Impact
* 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
* 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
* 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?
Expand All @@ -76,15 +52,25 @@ 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
* 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.

## Design Review Notes
Please post the notes from the Design Review here.