fbb52304e8
This seems helpful to reviewers (and probably also the author). Motivation is too high level to be able to properly review a design. We need a clear set of requirements to review the design against.
4.1 KiB
- Start Date: (fill me in with today's date, YYYY-MM-DD)
- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name)
- Discussion Issue: (GitHub issue this was discussed in before the RFC, if any)
- Implementation PR(s): (leave this empty)
Summary
Brief explanation of the feature.
Basic example
If the proposal involves a new or changed API, include a basic code example. Omit this section if it's not applicable.
Motivation
Why are we doing this? What use cases does it support? What is the expected outcome?
Please focus on explaining the motivation so that if this RFC is not accepted, the motivation could be used to develop alternative solutions. In other words, enumerate the constraints you are trying to solve without coupling them too closely to the solution you have in mind.
Requirements
What specific requirements does your design need to meet? This should ideally be a bulleted list of items you wish to achieve with your design. This can help everyone involved (including yourself!) make sure your design is robust enough to meet these requirements.
Once everyone has agreed upon the set of requirements for your design, we can use this list to review the detailed design.
Extensibility
Please also call out extensibility requirements. Is this proposal meant to be extended in the future? Are you adding a new API or set of models that others can build on in later? Please list these concerns here as well.
Non-Requirements
Call out things you don't want to discuss in detail during this review here, to help focus the conversation. This can include things you may build in the future based off this design, but don't wish to discuss in detail, in which case it may also be wise to explicitly list that extensibility in your design is a requirement.
This list can be high level and not detailed. It is to help focus the conversation on what you want to focus on.
Detailed design
This is the bulk of the RFC.
Explain the design in enough detail for somebody familiar with the framework to understand, and for somebody familiar with the implementation to implement. This should get into specifics and corner-cases, and include examples of how the feature is used. Any new terminology should be defined here.
How we teach this
What names and terminology work best for these concepts and why? How is this idea best presented? As a continuation of existing DataHub patterns, or as a wholly new one?
What audience or audiences would be impacted by this change? Just DataHub backend developers? Frontend developers? Users of the DataHub application itself?
Would the acceptance of this proposal mean the DataHub guides must be re-organized or altered? Does it change how DataHub is taught to new users at any level?
How should this feature be introduced and taught to existing audiences?
Drawbacks
Why should we not do this? Please consider the impact on teaching DataHub, on the integration of this feature with other existing and planned features, on the impact of the API churn on existing apps, etc.
There are tradeoffs to choosing any path, please attempt to identify them here.
Alternatives
What other designs have been considered? What is the impact of not doing this?
This section could also include prior art, that is, how other frameworks in the same domain have solved this problem.
Rollout / Adoption Strategy
If we implemented this proposal, how will existing users / developers adopt it? Is it a breaking change? Can we write automatic refactoring / migration tools? Can we provide a runtime adapter library for the original API it replaces?
Future Work
Describe any future projects, at a very high level, that will build off this proposal. This does not need to be exhaustive, nor does it need to be anything you work on. It just helps reviewers see how this can be used in the future, so they can help ensure your design is flexible enough.
Unresolved questions
Optional, but suggested for first drafts. What parts of the design are still TBD?