From ac7aedc5005e4743ff807f776f326c061c4b52b9 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Tue, 17 Dec 2019 17:08:04 -0800 Subject: [PATCH 1/7] Define RFC Process Adds readme with description of the RFC process and how to use it. Adds `0000-template.md` to be used as a template for creating new RFCs. --- 0000-template.md | 80 +++++++++++++++++++ LICENSE | 201 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 128 +++++++++++++++++++++++++++++- text/.gitkeep | 0 4 files changed, 408 insertions(+), 1 deletion(-) create mode 100644 0000-template.md create mode 100644 LICENSE create mode 100644 text/.gitkeep diff --git a/0000-template.md b/0000-template.md new file mode 100644 index 000000000..a5a303d80 --- /dev/null +++ b/0000-template.md @@ -0,0 +1,80 @@ +- 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: (leave this empty) + +# Summary + +Brief explanation of the feature. + +# Motivation + +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. + +# 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. + +# 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. + +# 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? + +# Prior Art + +Discuss priort art, both the good and the bad, in relation to this proposal. A +few examples of what this could include are. + +- + +# 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? + +# Future Possibilities + +THing 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. + +# Unresolved questions + +Optional, but suggested for first drafts. What parts of the design are still +TBD? diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..46c185646 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2018-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 5c84a1737..c862b272b 100644 --- a/README.md +++ b/README.md @@ -1 +1,127 @@ -AWS CDK RFCs +# AWS CDK RFCs - [Active RFC List](https://github.com/rust-lang/rfcs/pulls) + +Many changes, including bug fixes and documentation improvements can be +implemented and reviewed via the normal GitHub pull request workflow. + +Some changes though are "substantial", and we ask that these be put +through a bit of a design process and produce a consensus among the CDK +core team. + +The "RFC" (request for comments) process is intended to provide a +consistent and controlled path for new features to enter the project. + +[Active RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) + +## When to follow this process + +You should consider using this process if you intend to make "substantial" +changes to [AWS CDK](), [JSII](), or related tools. Some examples that would +benefit from an RFC are: + +- Any change to existing APIs that would break existing code. +- The removal of existing features or public APIs. +- The introduction of new idiomatic usage or conventions, even if they + do not include code changes to React itself. + +The RFC process is a great opportunity to get more eyeballs on your proposal +before it becomes a part of a released version of CDK. Quite often, even +proposals that seem "obvious" can be significantly improved once a wider +group of interested people have a chance to weigh in. + +The RFC process can also be helpful to encourage discussions about a proposed +feature as it is being designed, and incorporate important constraints into +the design while it's easier to change, before the design has been fully +implemented. + +If you submit a pull request to implement a new feature without going through +the RFC process, it may be closed with a polite request to submit an RFC first. + +Some changes do not require an RFC: + +- Bugfixes for known issues. +- Additions only likely to be _noticed by_ other developers-of-CDK, + invisible to users-of-CDK. +- Additions of missing L1 or L2 constructs. + +## What the process is + +In short, to get a major feature added to CDK, one usually first gets +the RFC merged into the RFC repo as a markdown file. At that point the RFC +is 'active' and may be implemented with the goal of eventual inclusion +into CDK. + +- Fork the RFC repo https://github.com/awslabs/aws-cdk-rfcs +- Copy `0000-template.md` to `text/0000-my-feature.md` (where 'my-feature' is + descriptive. Don't assign an RFC number yet. +- Fill in the RFC. Put care into the details: **RFCs that do not present + convincing motiviation, demonstrate understanding of the impact of the design, + or are disingenuous about the drawbacks or alternatives tend to be + poorly-received**. +- Submit a pull request. As a pull request the RFC will receive design + feedback from the core team and the larger community, and the author should + be prepared to make revisions in response. +- Build consensus and integrate feedback. RFCs that have broad support are + much more likely to make progress than those that don't receive any comments. +- Eventually, the team will decide whether the RFC is a candidate for + inclusion in CDK. +- RFCs that are candidates for inclusion in CDK will enter a "final comment + period" lasting 3 calendar days. The beginning of this period will be signaled + with a comment and label on the RFCs pull request. +- An RFC can be modified based upon feedback from the team and community. + Significant modifications may trigger a new final comment period. +- An RFC may be rejecte4d by the team after public discussion has settled and + comments have been made summarizing the rationale for rejection. A member of + the team should then close the RFCs associated pull request. +- An RFC may be accepted ad the close of its final comment period. A team + member will merge the RFCs associated pull request, at which point the RFC + will become 'active'. + +## The RFC life-cycle + +Once an RFC becomes active, then authors may implement it and submit the feature +as a mpull request to the aws-cdk or related repos. Becoming 'active' is not a +rubber stamp, and in particular still does not mean the feature will ultimately +be merged; it does mean that the core team has agreed to it in principle and are +amenable to merging it. + +Furthermore, the fact that a given RFC has been accepted and is 'active' implies +nothing about what priority is assigned to its implementation, nor whether +anybody is currently working on it. + +Modifications to active RFCs can be down in followup PRs. We strive to write +each RFC in a manner that it will refelct the final design of the feature; but +the nature of the process means that we cannot expect every merged RFC to +actually reflect what the end result will be at the time of the next major +release; therefore we try to keep each RFC document somewhat in sync with the +feature as planned, tracking such changes via followup pull requests to the +document. + +## Implementing an RFC + +The author of an RFC is not obligated to implement it. Of course, the RFC +author (like any other developer) is welcome to post an implementation for +review after the RFC has been accepted. + +If you are interested in working on the implementation for an 'active' RFC, but +cannot determine if someone else is already working on it, feel free to ask +(e.g. by leaving a comment on the associated issue). + +## Reviewing RFCs + +Each week the team will attempt to review some set of open RFC pull requests. + +Every RFC that we accept should have a core team champion, who will represent +the feature and its progress. + +## Help this is all too informal! + +The process is intended to be as lightweight as reasonable for the present +circumstances. As usual, we are trying to let the process be driven by consensus +and community norms, not impose more structure than necessary. + +**AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust RFC process], [React RFC process], and [Ember RFC process]** + +[yarn rfc process]: https://github.com/yarnpkg/rfcs +[rust rfc process]: https://github.com/rust-lang/rfcs +[react rfc process]: https://github.com/reactjs/rfcs +[ember rfc process]: https://github.com/emberjs/rfcs diff --git a/text/.gitkeep b/text/.gitkeep new file mode 100644 index 000000000..e69de29bb From 3dbda437e28e848f304df9e9a64407dd98c48cb2 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Wed, 18 Dec 2019 10:18:15 -0800 Subject: [PATCH 2/7] Apply suggestions from code review Co-Authored-By: Romain Marcadier-Muller Adds code of conduct and notice files. --- 0000-template.md | 38 +++++++++++++++++---------------- CODE_OF_CONDUCT.md | 5 +++++ NOTICE | 2 ++ README.md | 53 +++++++++++++++++++++++++++++----------------- rfc-states.svg | 1 + 5 files changed, 62 insertions(+), 37 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 NOTICE create mode 100644 rfc-states.svg diff --git a/0000-template.md b/0000-template.md index a5a303d80..5272e1a39 100644 --- a/0000-template.md +++ b/0000-template.md @@ -1,11 +1,13 @@ -- 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: (leave this empty) +--- +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) +--- # Summary -Brief explanation of the feature. +Brief description of the feature. # Motivation @@ -30,6 +32,12 @@ 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: @@ -49,21 +57,20 @@ There are tradeoffs to choosing any path. Attempt to identify them here. choosing them? - What is the impact of not doing this? -# Prior Art - -Discuss priort art, both the good and the bad, in relation to this proposal. A -few examples of what this could include are. - -- - # 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? +# 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? + # Future Possibilities -THing about what the natural extension and evolution of your proposal would be +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. @@ -73,8 +80,3 @@ 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. - -# Unresolved questions - -Optional, but suggested for first drafts. What parts of the design are still -TBD? diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..ec98f2b76 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +## Code of Conduct + +This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). +For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact +opensource-codeofconduct@amazon.com with any additional questions or comments. diff --git a/NOTICE b/NOTICE new file mode 100644 index 000000000..95fd48569 --- /dev/null +++ b/NOTICE @@ -0,0 +1,2 @@ +AWS Cloud Development Kit (AWS CDK) +Copyright 2018-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. diff --git a/README.md b/README.md index c862b272b..afc8737fa 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# AWS CDK RFCs - [Active RFC List](https://github.com/rust-lang/rfcs/pulls) +# AWS CDK RFCs - [Pending RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow. @@ -10,18 +10,18 @@ core team. The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the project. -[Active RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) +[Pending RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) ## When to follow this process You should consider using this process if you intend to make "substantial" -changes to [AWS CDK](), [JSII](), or related tools. Some examples that would +changes to [AWS CDK](https://github.com/aws/aws-cdk), [JSII](https://github.com/aws/jsii), or related tools. Some examples that would benefit from an RFC are: - Any change to existing APIs that would break existing code. - The removal of existing features or public APIs. - The introduction of new idiomatic usage or conventions, even if they - do not include code changes to React itself. + do not include code changes to CDK itself. The RFC process is a great opportunity to get more eyeballs on your proposal before it becomes a part of a released version of CDK. Quite often, even @@ -33,7 +33,7 @@ feature as it is being designed, and incorporate important constraints into the design while it's easier to change, before the design has been fully implemented. -If you submit a pull request to implement a new feature without going through +If you submit a pull request to implement a new major feature without going through the RFC process, it may be closed with a polite request to submit an RFC first. Some changes do not require an RFC: @@ -41,7 +41,9 @@ Some changes do not require an RFC: - Bugfixes for known issues. - Additions only likely to be _noticed by_ other developers-of-CDK, invisible to users-of-CDK. -- Additions of missing L1 or L2 constructs. +- Additions of missing L1 or L2 constructs. Unless the service and/or constructs + are especially complex or intentionally diverge from existing api design + best practices. ## What the process is @@ -50,36 +52,46 @@ the RFC merged into the RFC repo as a markdown file. At that point the RFC is 'active' and may be implemented with the goal of eventual inclusion into CDK. +- [Create a tracking issue](https://github.com/awslabs/aws-cdk-rfcs/issues/new) + for the proposed feature. - Fork the RFC repo https://github.com/awslabs/aws-cdk-rfcs - Copy `0000-template.md` to `text/0000-my-feature.md` (where 'my-feature' is descriptive. Don't assign an RFC number yet. -- Fill in the RFC. Put care into the details: **RFCs that do not present - convincing motiviation, demonstrate understanding of the impact of the design, - or are disingenuous about the drawbacks or alternatives tend to be - poorly-received**. +- Fill in the RFC. Put care into the details: **We welcome all honest efforts to + contribute.**. - Submit a pull request. As a pull request the RFC will receive design feedback from the core team and the larger community, and the author should be prepared to make revisions in response. + - The RFC number is the PR ID, change `0000-my-feature.md` to + `-my-feature.md` and add the PR # to the template document + where needed once it is known. + - Link to the RFC PR from the tracking issue. - Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments. - Eventually, the team will decide whether the RFC is a candidate for inclusion in CDK. - RFCs that are candidates for inclusion in CDK will enter a "final comment period" lasting 3 calendar days. The beginning of this period will be signaled - with a comment and label on the RFCs pull request. + by a team member adding a comment and label on the RFCs pull request. - An RFC can be modified based upon feedback from the team and community. Significant modifications may trigger a new final comment period. -- An RFC may be rejecte4d by the team after public discussion has settled and +- An RFC may be rejected by the team after public discussion has settled and comments have been made summarizing the rationale for rejection. A member of the team should then close the RFCs associated pull request. -- An RFC may be accepted ad the close of its final comment period. A team +- An RFC may be accepted at the close of its final comment period. A team member will merge the RFCs associated pull request, at which point the RFC will become 'active'. +A core team member will be assigned to 'champion' each proposal. They will +generally be the ones updating the PR's state as it moves through the process. +They can decide when a final comment period is triggered. + ## The RFC life-cycle +![rfc states](./rfc-states.svg) + Once an RFC becomes active, then authors may implement it and submit the feature -as a mpull request to the aws-cdk or related repos. Becoming 'active' is not a +as a pull request to the aws-cdk or related repos. Becoming 'active' is not a rubber stamp, and in particular still does not mean the feature will ultimately be merged; it does mean that the core team has agreed to it in principle and are amenable to merging it. @@ -88,8 +100,8 @@ Furthermore, the fact that a given RFC has been accepted and is 'active' implies nothing about what priority is assigned to its implementation, nor whether anybody is currently working on it. -Modifications to active RFCs can be down in followup PRs. We strive to write -each RFC in a manner that it will refelct the final design of the feature; but +Modifications to active RFCs can be done in followup PRs. We strive to write +each RFC in a manner that it will reflect the final design of the feature; but the nature of the process means that we cannot expect every merged RFC to actually reflect what the end result will be at the time of the next major release; therefore we try to keep each RFC document somewhat in sync with the @@ -98,9 +110,9 @@ document. ## Implementing an RFC -The author of an RFC is not obligated to implement it. Of course, the RFC -author (like any other developer) is welcome to post an implementation for -review after the RFC has been accepted. +While the author of an RFC (like any other developer) is welcome to offer an +implementation for review after the RFC has been accepted, they have no +obligation to do so. If you are interested in working on the implementation for an 'active' RFC, but cannot determine if someone else is already working on it, feel free to ask @@ -119,6 +131,9 @@ The process is intended to be as lightweight as reasonable for the present circumstances. As usual, we are trying to let the process be driven by consensus and community norms, not impose more structure than necessary. +The RFC process itself is subject to changes as dictated by the core team and +the community. + **AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust RFC process], [React RFC process], and [Ember RFC process]** [yarn rfc process]: https://github.com/yarnpkg/rfcs diff --git a/rfc-states.svg b/rfc-states.svg new file mode 100644 index 000000000..bd232af28 --- /dev/null +++ b/rfc-states.svg @@ -0,0 +1 @@ +issueTracking IssuependingPendingunder_reviewUnder ReviewfcpFinal Comment PeriodactiveActiveresolvedResolvedissue->pending rfc-pr createdpending->under_review core team member assignedunder_review->under_review revisionsunder_review->fcp core team approval fcp->under_review revisions requestedfcp->active mergedactive->resolved implementation complete \ No newline at end of file From ac4606ef00e846bdd70fc8e36469a098297cc0c8 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Wed, 1 Jan 2020 15:35:41 -0800 Subject: [PATCH 3/7] Adds issue and PR templates. Adds templates for guidance when creating tracking issues and pull requests. Clarifies rfc lifecycle states further in readme. --- .github/ISSUE_TEMPLATE/tracking-issue.md | 28 +++++ .github/PULL_REQUEST_TEMPLATE.md | 15 +++ 0000-template.md | 15 ++- CODE_OF_CONDUCT.md | 6 +- README.md | 154 ++++++++++++++--------- rfc-states.svg | 1 - 6 files changed, 157 insertions(+), 62 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/tracking-issue.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 rfc-states.svg diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md new file mode 100644 index 000000000..09c33be50 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -0,0 +1,28 @@ +--- +title: "RFC: title" +labels: tracking issue +--- + + + +|PR|Champion| +|--|--------| +|# | | + +## Description + + + +## Progress + + + + +- [x] - Tracking Issue Created +- [ ] - RFC PR Created +- [ ] - Core Team Member Assigned +- [ ] - Initial Approval / Final Comment Period +- [ ] - Ready For Implementation + + - [ ] implementation issue 1 +- [ ] - Resolved diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..9720919c4 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,15 @@ +--- +title: "RFC: # " <!-- <rfc#> is the tracking issue number and <title> is the rfc name --> +--- + +## Notes + +<!-- Call out suggestions for reviewers to discuss --> + +<!-- link to the proposal document for readers to view rendered version --> +### [Rendered](/my-fork/text/xxxx.md) + +--- + +_By submitting this pull request, I confirm that my contribution is made under +the terms of the Apache-2.0 license_ diff --git a/0000-template.md b/0000-template.md index 5272e1a39..9badef82d 100644 --- a/0000-template.md +++ b/0000-template.md @@ -24,6 +24,11 @@ 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. + # Detailed Design This is the bulk of the RFC. Explain the design in enough detail for somebody @@ -64,9 +69,13 @@ 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 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index ec98f2b76..8f18aeabb 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,5 +1,7 @@ ## Code of Conduct -This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). -For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact +This project has adopted the +[Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). For +more information see the +[Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact opensource-codeofconduct@amazon.com with any additional questions or comments. diff --git a/README.md b/README.md index afc8737fa..3e5b47b4d 100644 --- a/README.md +++ b/README.md @@ -3,73 +3,78 @@ Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow. -Some changes though are "substantial", and we ask that these be put -through a bit of a design process and produce a consensus among the CDK -core team. +Some changes though are "substantial", and we ask that these be put through a +bit of a design process and produce a consensus among the CDK core team. -The "RFC" (request for comments) process is intended to provide a -consistent and controlled path for new features to enter the project. +The "RFC" (request for comments) process is intended to provide a consistent and +controlled path for new features to enter the project. [Pending RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) ## When to follow this process You should consider using this process if you intend to make "substantial" -changes to [AWS CDK](https://github.com/aws/aws-cdk), [JSII](https://github.com/aws/jsii), or related tools. Some examples that would +changes to [AWS CDK](https://github.com/aws/aws-cdk), +[JSII](https://github.com/aws/jsii), or related tools. Some examples that would benefit from an RFC are: -- Any change to existing APIs that would break existing code. +- Any change to existing APIs that could break existing code. - The removal of existing features or public APIs. -- The introduction of new idiomatic usage or conventions, even if they - do not include code changes to CDK itself. +- The introduction of new idiomatic usage or conventions, even if they do not + include code changes to CDK itself. +- Changes to the documented contribution workflow. +- Features that cross multiple construct libraries. +- Additions or changes to framework capabilities. +- Additions or changes to formal specifications like cloud assembly, tree.json, + jsii, etc. The RFC process is a great opportunity to get more eyeballs on your proposal before it becomes a part of a released version of CDK. Quite often, even -proposals that seem "obvious" can be significantly improved once a wider -group of interested people have a chance to weigh in. +proposals that seem "obvious" can be significantly improved once a wider group +of interested people have a chance to weigh in. The RFC process can also be helpful to encourage discussions about a proposed -feature as it is being designed, and incorporate important constraints into -the design while it's easier to change, before the design has been fully +feature as it is being designed, and incorporate important constraints into the +design while it's easier to change, before the design has been fully implemented. -If you submit a pull request to implement a new major feature without going through -the RFC process, it may be closed with a polite request to submit an RFC first. +If you submit a pull request to implement a new major feature without going +through the RFC process, it may be closed with a polite request to submit an RFC +first. Some changes do not require an RFC: - Bugfixes for known issues. -- Additions only likely to be _noticed by_ other developers-of-CDK, - invisible to users-of-CDK. +- Additions only likely to be _noticed by_ other developers-of-CDK, invisible to + users-of-CDK. - Additions of missing L1 or L2 constructs. Unless the service and/or constructs - are especially complex or intentionally diverge from existing api design - best practices. + are especially complex or intentionally diverge from existing api design best + practices. ## What the process is -In short, to get a major feature added to CDK, one usually first gets -the RFC merged into the RFC repo as a markdown file. At that point the RFC -is 'active' and may be implemented with the goal of eventual inclusion -into CDK. +In short, to get a major feature added to CDK, one usually first gets the RFC +merged into the RFC repo as a markdown file. At that point the RFC is 'ready' +and may be implemented with the goal of eventual inclusion into CDK. -- [Create a tracking issue](https://github.com/awslabs/aws-cdk-rfcs/issues/new) - for the proposed feature. +- [Create a tracking issue](https://github.com/awslabs/aws-cdk-rfcs/issues/new?template=tracking-issue.md) + for the proposed feature if one doesn't already exist. Use the tracking issue + template as a guide. If a tracking issue already exists, make sure to update + it and assign it to let others know you're working on a proposal. - Fork the RFC repo https://github.com/awslabs/aws-cdk-rfcs -- Copy `0000-template.md` to `text/0000-my-feature.md` (where 'my-feature' is - descriptive. Don't assign an RFC number yet. +- Copy `0000-template.md` to `text/<rfc#>-<my-feature>.md` where <rfc#> is the + tracking issue number and <my-feature> is the rfc title. - Fill in the RFC. Put care into the details: **We welcome all honest efforts to contribute.**. -- Submit a pull request. As a pull request the RFC will receive design - feedback from the core team and the larger community, and the author should - be prepared to make revisions in response. - - The RFC number is the PR ID, change `0000-my-feature.md` to - `<pr-number>-my-feature.md` and add the PR # to the template document - where needed once it is known. - - Link to the RFC PR from the tracking issue. -- Build consensus and integrate feedback. RFCs that have broad support are - much more likely to make progress than those that don't receive any comments. -- Eventually, the team will decide whether the RFC is a candidate for - inclusion in CDK. +- Submit a pull request with the title `RFC: <rfc#> <title>` where <rfc#> is the + tracking issue number and title is the name of the proposal. As a pull request + the RFC will receive design feedback from the core team and the larger + community, and the author should be prepared to make revisions in response. + - Update the tracking issue with a link to the RFC PR. +- Build consensus and integrate feedback. RFCs that have broad support are much + more likely to make progress than those that don't receive any comments. +- Eventually, the team will decide whether the RFC is a candidate for inclusion + in CDK. - RFCs that are candidates for inclusion in CDK will enter a "final comment period" lasting 3 calendar days. The beginning of this period will be signaled by a team member adding a comment and label on the RFCs pull request. @@ -78,31 +83,67 @@ into CDK. - An RFC may be rejected by the team after public discussion has settled and comments have been made summarizing the rationale for rejection. A member of the team should then close the RFCs associated pull request. -- An RFC may be accepted at the close of its final comment period. A team - member will merge the RFCs associated pull request, at which point the RFC - will become 'active'. +- An RFC may be accepted at the close of its final comment period. A team member + will merge the RFCs associated pull request, at which point the RFC will + become 'ready'. A core team member will be assigned to 'champion' each proposal. They will -generally be the ones updating the PR's state as it moves through the process. -They can decide when a final comment period is triggered. +generally be the ones updating the RFCs state in the tracking issue as it moves +through the process. They can decide when a final comment period is triggered. ## The RFC life-cycle -![rfc states](./rfc-states.svg) - -Once an RFC becomes active, then authors may implement it and submit the feature -as a pull request to the aws-cdk or related repos. Becoming 'active' is not a +![rfc-states](https://g.gravizo.com/svg?digraph%20states%20{node%20[shape=ellipse];proposed%20[label%20=%20%22Proposed%22];pending%20[label%20=%20%22Pending%22];fcp%20[label%20=%20%22Final%20Comment%20Period%22];ready%20[label%20=%20%22Ready%22];resolved%20[label%20=%20%22Resolved%22];proposed%20-%3E%20pending%20[label%20=%20%22%20rfc%20pr%20created%22];pending%20-%3E%20pending%20[label%20=%20%22%20revisions%22];pending%20-%3E%20fcp%20[label%20=%20%22core%20team%20approval%20%20%20%20%22];fcp%20-%3E%20pending%20[label%20=%20%22%20revision%20requested%22];fcp%20-%3E%20ready%20[label%20=%20%22%20merged%22];ready%20-%3E%20resolved%20[label%20=%20%22%20implementation%20complete%22];}) + +<!-- for later reference from renderer --> +<details> +<summary></summary> +custom_mark10 + digraph states { + node [shape=ellipse]; + proposed [label = "Proposed"]; + pending [label = "Pending"]; + fcp [label = "Final Comment Period"]; + ready [label = "Ready"]; + resolved [label = "Resolved"]; + proposed -> pending [label = " rfc pr created"]; + pending -> pending [label = " revisions"]; + pending -> fcp [label = "core team approval "]; + fcp -> pending [label = " revision requested"]; + fcp -> ready [label = " merged"]; + ready -> resolved [label = " implementation complete"]; + } +custom_mark10 +</details> + +An RFC flows through the following states. + +1. Proposed - A tracking issue has been created with a basic outline of the + proposal. +2. Pending - An RFC document has been written with a detailed design and a PR is + under review. +3. Final Comment Period - A core team member has been assigned to oversee the + proposal and at least 1 core team member has approved the RFC PR. + - An RFC may be reverted or closed during final comment period if a member of + the core team or community raises a previously unforeseen issue that is + cause for concern. +4. Ready - Final comment period is complete and the PR is merged. +5. Resolved - The implementation is complete and merged across appropriate + repositories. + +Once an RFC becomes ready, then authors may implement it and submit the feature +as a pull request to the aws-cdk or related repos. Becoming 'ready' is not a rubber stamp, and in particular still does not mean the feature will ultimately be merged; it does mean that the core team has agreed to it in principle and are amenable to merging it. -Furthermore, the fact that a given RFC has been accepted and is 'active' implies +Furthermore, the fact that a given RFC has been accepted and is 'ready' implies nothing about what priority is assigned to its implementation, nor whether anybody is currently working on it. -Modifications to active RFCs can be done in followup PRs. We strive to write -each RFC in a manner that it will reflect the final design of the feature; but -the nature of the process means that we cannot expect every merged RFC to +Modifications to RFCs marked 'ready' can be done in followup PRs. We strive to +write each RFC in a manner that it will reflect the final design of the feature; +but the nature of the process means that we cannot expect every merged RFC to actually reflect what the end result will be at the time of the next major release; therefore we try to keep each RFC document somewhat in sync with the feature as planned, tracking such changes via followup pull requests to the @@ -114,9 +155,9 @@ While the author of an RFC (like any other developer) is welcome to offer an implementation for review after the RFC has been accepted, they have no obligation to do so. -If you are interested in working on the implementation for an 'active' RFC, but -cannot determine if someone else is already working on it, feel free to ask -(e.g. by leaving a comment on the associated issue). +If you are interested in working on the implementation for an RFC marked +'ready', but cannot determine if someone else is already working on it, feel +free to ask (e.g. by leaving a comment on the associated tracking issue). ## Reviewing RFCs @@ -127,14 +168,15 @@ the feature and its progress. ## Help this is all too informal! -The process is intended to be as lightweight as reasonable for the present +The process is intended to be as lightweight and reasonable for the present circumstances. As usual, we are trying to let the process be driven by consensus and community norms, not impose more structure than necessary. The RFC process itself is subject to changes as dictated by the core team and the community. -**AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust RFC process], [React RFC process], and [Ember RFC process]** +**AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust +RFC process], [React RFC process], and [Ember RFC process]** [yarn rfc process]: https://github.com/yarnpkg/rfcs [rust rfc process]: https://github.com/rust-lang/rfcs diff --git a/rfc-states.svg b/rfc-states.svg deleted file mode 100644 index bd232af28..000000000 --- a/rfc-states.svg +++ /dev/null @@ -1 +0,0 @@ -<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="281.2pt" height="488pt" viewBox="0 0 281.2 488"><style type="text/css">.dashed {stroke-dasharray: 5,5} .dotted {stroke-dasharray: 1,5} .overlay {fill: none; pointer-events: all}</style><g><g transform="translate(4, 484)"><polygon stroke="#fffffe" stroke-opacity="0" fill="#ffffff" points="-4,4 -4,-484 277.2,-484 277.2,4"></polygon><g class="node"><title>issueTracking IssuependingPendingunder_reviewUnder ReviewfcpFinal Comment PeriodactiveActiveresolvedResolvedissue->pending rfc-pr createdpending->under_review core team member assignedunder_review->under_review revisionsunder_review->fcp core team approval fcp->under_review revisions requestedfcp->active mergedactive->resolved implementation complete \ No newline at end of file From 814fcfc6731b16b14867e268ed82cd0d4c48ab09 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Thu, 2 Jan 2020 16:51:04 -0800 Subject: [PATCH 4/7] Shorten Intro and Ligthen Language Shorten the intro section and explain the repos use for tracking the state of upcoming features. Add "What does all this mean", "What is an RFC", and "Contributions" section to further encourage community participation. --- README.md | 116 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 82 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 3e5b47b4d..6d92bf2ba 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,65 @@ # AWS CDK RFCs - [Pending RFC List](https://github.com/awslabs/aws-cdk-rfcs/pulls) -Many changes, including bug fixes and documentation improvements can be -implemented and reviewed via the normal GitHub pull request workflow. +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. -Some changes though are "substantial", and we ask that these be put through a -bit of a design process and produce a consensus among the CDK core team. - -The "RFC" (request for comments) process is intended to provide a consistent and -controlled path for new features to enter the project. +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) +## What does all this mean?! + +This document is a lot of information about process thats meant to help guide. +It is not a set of rules that need to be strictly applied. It is designed to +help contributors (and thats you!) become more involved with the tools that they +rely on. All efforts to contribute are encouraged and appreciated. + +## What is an RFC? + +An RFC is a document that proposes and details a change or addition to the CDK, +JSII, and other related tooling. It also is a process for reviewing and +discussing the proposal and tracking its implementation. "Request for Comments" +means a request for discussion and oversight about the future of the CDK and +JSII from contributors and users. It is an open forum for suggestions, +questions, and feedback. + +The process is intended to be as lightweight and reasonable as possible for the +present circumstances. As usual, we are trying to let the process be driven by +consensus and community norms, not impose more structure than necessary. + +The RFC process itself is subject to changes as dictated by the core team and +the community. Proposals can include proposed changes to the RFC process itself +to better serve contributors. + +## Contributions + +Contributions are welcome from anyone in a variety of ways. + +- [Reviewing and dicussing existing proposals](#reviewing-rfcs) + +Comments are welcome on proposal tracking issues and RFC pull requests. This can +be to show support for a feature that you're really interested in having, or to +point out possible red flags or downsides to the change. + +- [Creating new proposals](#what-the-process-is) + +If a feature or change you think is needed hasn't been proposed, create a new +tracking issue. + +- [Writing RFC documents](#what-the-process-is) + +If you're interested in helping to design an existing proposal, comment on the +tracking issue and get started on an RFC document. + +- [Implementing proposals that are ready](#implementing-an-rfc) + +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". + ## When to follow this process You should consider using this process if you intend to make "substantial" @@ -21,15 +70,15 @@ benefit from an RFC are: - Any change to existing APIs that could break existing code. - The removal of existing features or public APIs. - The introduction of new idiomatic usage or conventions, even if they do not - include code changes to CDK itself. + include code changes to CDK or JSII themselves. - Changes to the documented contribution workflow. - Features that cross multiple construct libraries. - Additions or changes to framework capabilities. - Additions or changes to formal specifications like cloud assembly, tree.json, - jsii, etc. + JSII, etc. The RFC process is a great opportunity to get more eyeballs on your proposal -before it becomes a part of a released version of CDK. Quite often, even +before it becomes a part of a released version of CDK/JSII. Quite often, even proposals that seem "obvious" can be significantly improved once a wider group of interested people have a chance to weigh in. @@ -45,17 +94,21 @@ first. Some changes do not require an RFC: - Bugfixes for known issues. -- Additions only likely to be _noticed by_ other developers-of-CDK, invisible to - users-of-CDK. +- Additions only likely to be _noticed by_ other developers of CDK/JSII, invisible + to users of CDK/JSII. - Additions of missing L1 or L2 constructs. Unless the service and/or constructs are especially complex or intentionally diverge from existing api design best practices. +If you're not sure whether your change requires an RFC, feel free to create an +issue and ask. + ## What the process is -In short, to get a major feature added to CDK, one usually first gets the RFC -merged into the RFC repo as a markdown file. At that point the RFC is 'ready' -and may be implemented with the goal of eventual inclusion into CDK. +In short, to get a major feature added to CDK/JSII, one usually first gets the +RFC merged into the RFC repo as a markdown file. At that point the RFC is +'ready' and may be implemented with the goal of eventual inclusion into +CDK/JSII. - [Create a tracking issue](https://github.com/awslabs/aws-cdk-rfcs/issues/new?template=tracking-issue.md) for the proposed feature if one doesn't already exist. Use the tracking issue @@ -74,8 +127,8 @@ and may be implemented with the goal of eventual inclusion into CDK. - Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments. - Eventually, the team will decide whether the RFC is a candidate for inclusion - in CDK. -- RFCs that are candidates for inclusion in CDK will enter a "final comment + in CDK/JSII. +- RFCs that are candidates for inclusion in CDK/JSII will enter a "final comment period" lasting 3 calendar days. The beginning of this period will be signaled by a team member adding a comment and label on the RFCs pull request. - An RFC can be modified based upon feedback from the team and community. @@ -91,7 +144,7 @@ A core team member will be assigned to 'champion' each proposal. They will generally be the ones updating the RFCs state in the tracking issue as it moves through the process. They can decide when a final comment period is triggered. -## The RFC life-cycle +## The RFC Life Cycle ![rfc-states](https://g.gravizo.com/svg?digraph%20states%20{node%20[shape=ellipse];proposed%20[label%20=%20%22Proposed%22];pending%20[label%20=%20%22Pending%22];fcp%20[label%20=%20%22Final%20Comment%20Period%22];ready%20[label%20=%20%22Ready%22];resolved%20[label%20=%20%22Resolved%22];proposed%20-%3E%20pending%20[label%20=%20%22%20rfc%20pr%20created%22];pending%20-%3E%20pending%20[label%20=%20%22%20revisions%22];pending%20-%3E%20fcp%20[label%20=%20%22core%20team%20approval%20%20%20%20%22];fcp%20-%3E%20pending%20[label%20=%20%22%20revision%20requested%22];fcp%20-%3E%20ready%20[label%20=%20%22%20merged%22];ready%20-%3E%20resolved%20[label%20=%20%22%20implementation%20complete%22];}) @@ -149,6 +202,17 @@ release; therefore we try to keep each RFC document somewhat in sync with the feature as planned, tracking such changes via followup pull requests to the document. +## Reviewing RFCs + +Each week the team will attempt to review some set of open RFC pull requests. +Comments and feedback on proposals in any state of the process are welcome and +encouraged. + +Every RFC that we accept should have a core team champion, who will represent +the feature and its progress. When an RFC is merged, we try to label the +tracking with an estimation of effort required for implementation. These are +general "t-shirt size" estimates e.g. small, medium, large. + ## Implementing an RFC While the author of an RFC (like any other developer) is welcome to offer an @@ -159,22 +223,6 @@ If you are interested in working on the implementation for an RFC marked 'ready', but cannot determine if someone else is already working on it, feel free to ask (e.g. by leaving a comment on the associated tracking issue). -## Reviewing RFCs - -Each week the team will attempt to review some set of open RFC pull requests. - -Every RFC that we accept should have a core team champion, who will represent -the feature and its progress. - -## Help this is all too informal! - -The process is intended to be as lightweight and reasonable for the present -circumstances. As usual, we are trying to let the process be driven by consensus -and community norms, not impose more structure than necessary. - -The RFC process itself is subject to changes as dictated by the core team and -the community. - **AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust RFC process], [React RFC process], and [Ember RFC process]** From 4470b03da3021771408a5236b8cf174897a7d230 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Fri, 3 Jan 2020 15:39:15 -0800 Subject: [PATCH 5/7] 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 | 16 ++-- 0000-template.md | 111 ++++++++++++----------- README.md | 14 ++- 3 files changed, 73 insertions(+), 68 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md index 09c33be50..61a55b583 100644 --- a/.github/ISSUE_TEMPLATE/tracking-issue.md +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -1,6 +1,6 @@ --- -title: "RFC: title" -labels: tracking issue +title: proposal title +labels: tracking issue, status/proposed --- @@ -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..7b699803c 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 From 7119d3dca7898d835552b642c9284b481e9016c6 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Sun, 5 Jan 2020 11:06:32 -0800 Subject: [PATCH 6/7] Update README.md Co-Authored-By: Elad Ben-Israel --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7b699803c..3ecaae6c3 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ existing proposals. - [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+) +- [Resolved RFCs](https://github.com/awslabs/aws-cdk-rfcs/issues?utf8=%E2%9C%93&q=label%3Astatus%2Fresolved) ## What does all this mean?! From ad16c16c80a1e7761310195339bb7413490a9793 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Sun, 5 Jan 2020 11:10:31 -0800 Subject: [PATCH 7/7] Fix broken link --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 3ecaae6c3..84094fd28 100644 --- a/README.md +++ b/README.md @@ -61,8 +61,7 @@ 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".] -(https://github.com/awslabs/aws-cdk-rfcs/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3Astatus%2Fready+label%3Aeffort%2Fsmall) +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