-
Notifications
You must be signed in to change notification settings - Fork 83
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Reduce the complexity of RFCs by simplifying the template to a PR/FAQ format.
- Loading branch information
Elad Ben-Israel
authored
Oct 8, 2020
1 parent
e712acc
commit f4a0608
Showing
1 changed file
with
96 additions
and
73 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,102 +1,125 @@ | ||
| --- | ||
| feature name: (fill me in with a unique identifier, my-awesome-feature) | ||
| start date: (fill me in with today's date, YYYY-MM-DD) | ||
| rfc pr: (leave this empty) | ||
| related issue: (tracking issue number) | ||
| rfc pr: [#xxx](https://github.com/aws/aws-cdk-rfcs/pull/xxx) <-- fill this after you've already created the PR | ||
| tracking issue: https://github.com/aws/aws-cdk-rfcs/issues/yyy | ||
| --- | ||
|
|
||
| # Summary | ||
| # [TITLE] | ||
|
|
||
| > Brief description of the feature. | ||
| > One sentence: brief description of the feature from a user perspective. | ||
| # README | ||
| ## Working Backwards | ||
|
|
||
| > Work backwards from the README: pretend that this feature is already | ||
| > implemented and write the README section. It will help you think about your | ||
| > proposal from a user experience point of view. If a README format does not | ||
| > make sense for your proposal, write a "Press Release" which announces your new | ||
| > feature instead. | ||
| > This section should contain one or more "artifacts from the future", as if the | ||
| > feature was already released and we are publishing its CHANGELOG, README | ||
| > and optionally a PRESS RELEASE. | ||
| > | ||
| > This is the most important section of your RFC. It's a powerful thought | ||
| > exercise which will challenge you to truly think about this feature from a | ||
| > user's point of view. | ||
| # Motivation | ||
| ### CHANGELOG | ||
|
|
||
| > Why are we doing this? What use cases does it support? What is the expected | ||
| > outcome? | ||
| > Write the changelog entry for this feature in conventional form (e.g. | ||
| > `feat(eks): cluster tags`). | ||
| > | ||
| > If this change includes a breaking change, include a `BREAKING CHANGE` clause | ||
| > with information on how to migrate. If migration is complicated, refer to a | ||
| > fictional GitHub issue and add its contents here. | ||
| # Design Summary | ||
| ### README | ||
|
|
||
| > Summarize the approach of the feature design in a couple of sentences. Call out | ||
| > any known patterns or best practices the design is based around. | ||
| > If this is a new feature, write the README section which describes this new | ||
| > feature. It should describe the feature and walk users through usage examples | ||
| > and description of the various options and behavior. | ||
| # Detailed Design | ||
| ### PRESS RELEASE | ||
|
|
||
| > This is the bulk of the RFC. Explain the design in enough detail for somebody | ||
| > familiar with CDK 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. | ||
| > | ||
| > Include any diagrams and/or visualizations that help to demonstrate the design. | ||
| > Here are some tools that we often use: | ||
| > | ||
| > - [Graphviz](http://graphviz.it/#/gallery/structs.gv) | ||
| > - [PlantText](https://www.planttext.com) | ||
| > If this is a major feature (~6 months of work), write the PRESS RELEASE which | ||
| > announces this feature. The press release is a single page that includes 7 | ||
| > paragraphs: (1) summary, (2) problem, (3) solution, (4) leader quote, (5) user | ||
| > experience, (6) customer testimonial and (7) one sentence call to action. | ||
| # Drawbacks | ||
| ## FAQ | ||
|
|
||
| > Why should we _not_ do this? Please consider: | ||
| > | ||
| > - implementation cost, both in term of code size and complexity | ||
| > - whether the proposed feature can be implemented in user space | ||
| > - the impact on teaching people how to use CDK | ||
| > - integration of this feature with other existing and planned features | ||
| > - cost of migrating existing CDK applications (is it a breaking change?) | ||
| > This section should contain answers to questions customers will likely ask about | ||
| > this release. Similar to the working backwards section, this section should be | ||
| > written "from the future" in a language as if the feature is now released. | ||
| > | ||
| > There are tradeoffs to choosing any path. Attempt to identify them here. | ||
| > The template includes a bunch of common questions, and you should add | ||
| > questions that might be relevant to this feature. | ||
| ### What are we launching today? | ||
|
|
||
| > What exactly are we launching? Is this a new feature in an existing module? A | ||
| > new module? A whole framework? A change in the CLI? | ||
| ### Why should I use this feature? | ||
|
|
||
| > Describe use cases that are addressed by this feature. | ||
| ## Internal FAQ | ||
|
|
||
| # Rationale and Alternatives | ||
| > The goal of this section is to help decide if this RFC should be implemented. | ||
| > It should include answers to questions that the team is likely ask. Contrary | ||
| > to the rest of the RFC, answers should be written "from the present" and | ||
| > likely discuss design approach, implementation plans, alternative considered | ||
| > and other considerations that will help decide if this RFC should be | ||
| > implemented. | ||
| > - Why is this design the best in the space of possible designs? | ||
| > - What other designs have been considered and what is the rationale for not | ||
| > choosing them? | ||
| > - What is the impact of not doing this? | ||
| ### Why are we doing this? | ||
|
|
||
| # Adoption Strategy | ||
| > What is the motivation for this change? | ||
| > If we implement this proposal, how will existing CDK developers adopt it? Is | ||
| > this a breaking change? How can we assist in adoption? | ||
| ### Why should we _not_ do this? | ||
|
|
||
| # Unresolved questions | ||
| > Is there a way to address this use case with the current product? What are the | ||
| > downsides of implementing this feature? | ||
| > - What parts of the design do you expect to resolve through the RFC process | ||
| > before this gets merged? | ||
| > - What parts of the design do you expect to resolve through the implementation | ||
| > of this feature before stabilization? | ||
| > - What related issues do you consider out of scope for this RFC that could be | ||
| > addressed in the future independently of the solution that comes out of this | ||
| > RFC? | ||
| ### What changes are required to enable this change? | ||
|
|
||
| # Future Possibilities | ||
| > Briefly describe the high-level design approach for implementing this feature. | ||
| > | ||
| > As appropriate, you can add an appendix with a more detailed design document. | ||
| > | ||
| > This is a good place to reference a prototype or proof of concept, which is | ||
| > highly recommended for most RFCs. | ||
| ### Is this a breaking change? | ||
|
|
||
| > Think about what the natural extension and evolution of your proposal would be | ||
| > and how it would affect CDK as whole. Try to use this section as a tool to more | ||
| > fully consider all possible interactions with the project and ecosystem in your | ||
| > proposal. Also consider how this fits into the roadmap for the project. | ||
| > If the answer is no. Otherwise: | ||
| > | ||
| > This is a good place to "dump ideas", if they are out of scope for the RFC you | ||
| > are writing but are otherwise related. | ||
| > Describe what ways did you consider to deliver this without breaking users? | ||
| > | ||
| > If you have tried and cannot think of any future possibilities, you may simply | ||
| > state that you cannot think of anything. | ||
| > Make sure to include a `BREAKING CHANGE` clause under the CHANGELOG section with a description of the breaking | ||
| > changes and the migration path. | ||
| ### What are the drawbacks of this solution? | ||
|
|
||
| > Describe any problems/risks that can be introduced if we implement this RFC. | ||
| # Implementation Plan | ||
| ### What alternative solutions did you consider? | ||
|
|
||
| INTENTIONALLY LEFT BLANK: an implementation plan will be added when the RFC is | ||
| scheduled for implementation. | ||
| > Briefly describe alternative approaches that you considered. If there are | ||
| > hairy details, include them in an appendix. | ||
| > The implementation plan should analyze all the tasks needed in order to | ||
| > implement this RFC, and the planned order of implementation based on | ||
| > dependencies and analysis of the critical path. | ||
| ### What is the high level implementation plan? | ||
|
|
||
| > Describe your plan on how to deliver this feature from prototyping to GA. | ||
| > Especially think about how to "bake" it in the open and get constant feedback | ||
| > from users before you stabilize the APIs. | ||
| > | ||
| > Either add the plan here or add link which references a separate document | ||
| > and/or a GitHub Project Board (and reference it here) which manages the | ||
| > execution of your plan. | ||
| > If you have a project board with your implementation plan, this is a good | ||
| > place to link to it. | ||
| ### Are there any open issues that need to be addressed later? | ||
|
|
||
| > Describe any major open issues that this RFC did not take into account. Once | ||
| > the RFC is approved, create GitHub issues for these issues and update this RFC | ||
| > of the project board with these issue IDs. | ||
| ## Appendix: .... | ||
|
|
||
| Feel free to add any number of appendices as you see fit. Appendices are | ||
| expected to allow readers to dive deeper to certain sections if they like. For | ||
| example, you can include an appendix which describes the detailed design of an | ||
| algorithm and reference it from the FAQ. |