From 01c7ac7ca9d665187c9ec50fea5e535ee9ed14f1 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Fri, 3 Jan 2020 15:39:15 -0800 Subject: [PATCH] Add Quicklinks and Cleanup Add quicklinks to RFC tracking issues in various states. Cleanup some formatting. Move bodies of template sections into blockquotes. --- .github/ISSUE_TEMPLATE/tracking-issue.md | 14 +-- 0000-template.md | 111 ++++++++++++----------- README.md | 14 ++- 3 files changed, 72 insertions(+), 67 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md index 09c33be50..16290af70 100644 --- a/.github/ISSUE_TEMPLATE/tracking-issue.md +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -1,5 +1,5 @@ --- -title: "RFC: title" +title: proposal title labels: tracking issue --- @@ -18,11 +18,11 @@ labels: tracking issue -- [x] - Tracking Issue Created -- [ ] - RFC PR Created -- [ ] - Core Team Member Assigned -- [ ] - Initial Approval / Final Comment Period -- [ ] - Ready For Implementation +- [x] Tracking Issue Created +- [ ] RFC PR Created +- [ ] Core Team Member Assigned +- [ ] Initial Approval / Final Comment Period +- [ ] Ready For Implementation - [ ] implementation issue 1 -- [ ] - Resolved +- [ ] Resolved diff --git a/0000-template.md b/0000-template.md index 9badef82d..b77f4f102 100644 --- a/0000-template.md +++ b/0000-template.md @@ -5,87 +5,88 @@ rfc pr: (leave this empty) related issue: (tracking issue number) --- + # Summary -Brief description of the feature. +> Brief description of the feature. # Motivation -Why are we doing this? What use cases does it support? What is the expected -outcome? +> Why are we doing this? What use cases does it support? What is the expected +> outcome? # Basic Example -If the proposal involves a new or changed API, include a basic code example. -Omit this section if it's not applicable. - -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. +> If the proposal involves a new or changed API, include a basic code example. +> Omit this section if it's not applicable. +> +> 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. # Design Summary -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. +> 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. # Detailed Design -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) +> 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) # Drawbacks -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?) - -There are tradeoffs to choosing any path. Attempt to identify them here. +> 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?) +> +> There are tradeoffs to choosing any path. Attempt to identify them here. # Rationale and Alternatives -- 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 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? # Adoption Strategy -If we implement this proposal, how will existing CDK developers adopt it? Is -this a breaking change? How can we assist in adoption? +> If we implement this proposal, how will existing CDK developers adopt it? Is +> this a breaking change? How can we assist in adoption? # Unresolved questions -- 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 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? # Future Possibilities -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. - -This is a good place to "dump ideas", if they are out of scope for the RFC you -are writing but are otherwise related. - -If you have tried and cannot think of any future possibilities, you may simply -state that you cannot think of anything. +> 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. +> +> This is a good place to "dump ideas", if they are out of scope for the RFC you +> are writing but are otherwise related. +> +> If you have tried and cannot think of any future possibilities, you may simply +> state that you cannot think of anything. diff --git a/README.md b/README.md index 6d92bf2ba..5f0686c8f 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,16 @@ -# AWS CDK RFCs - [Pending RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) +# AWS CDK RFCs - [RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) This repo is a place to propose and track upcoming changes to CDK, JSII, and other related projects. It also is a great place to learn about the current and -future state of the libraries. +future state of the libraries and to discover projects for contribution. See [The RFC Life Cycle](#the-rfc-life-cycle) to learn more about the states of existing proposals. -[Pending RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) +[Proposed RFCs](https://github.com/awslabs/aws-cdk-rfcs/labels/status%2Fproposed) +[Pending RFCs](https://github.com/awslabs/aws-cdk-rfcs/labels/status%2Fpending) +[Ready RFCs](https://github.com/awslabs/aws-cdk-rfcs/labels/status%2Fready) +[Resolved RFCs](https://github.com/awslabs/aws-cdk-rfcs/issues?utf8=%E2%9C%93&q=label%3Astatus%2Fresolved+) ## What does all this mean?! @@ -57,8 +60,9 @@ tracking issue and get started on an RFC document. Once a proposal has been reviewed and is ready, contributions to its implementation are greatly appreciated. We try to estimate the effort needed to -implement a proposal. If you're looking for a good introductory project, look -for proposals that are labeled "ready" and "effort/small". +implement a proposal. If you're looking for a good introductory project, [look +for proposals that are labeled "ready" and "effort/small".] +(https://github.com/awslabs/aws-cdk-rfcs/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3Astatus%2Fready+label%3Aeffort%2Fsmall) ## When to follow this process