diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md new file mode 100644 index 000000000..61a55b583 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -0,0 +1,28 @@ +--- +title: proposal title +labels: tracking issue, status/proposed +--- + + + +|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 new file mode 100644 index 000000000..b77f4f102 --- /dev/null +++ b/0000-template.md @@ -0,0 +1,92 @@ +--- +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) +--- + +<!-- replace the blockquoted sections with your content --> +# Summary + +> Brief description 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. + +# 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 +> 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. + +# 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? + +# 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 + +> 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/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..8f18aeabb --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +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 +opensource-codeofconduct@amazon.com with any additional questions or comments. 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/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 5c84a1737..84094fd28 100644 --- a/README.md +++ b/README.md @@ -1 +1,235 @@ -AWS CDK RFCs +# 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 and to discover projects for contribution. + +See [The RFC Life Cycle](#the-rfc-life-cycle) to learn more about the states of +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) + +## 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".](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 + +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 +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 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. + +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/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. + +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 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/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/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 + 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/<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 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/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. + Significant modifications may trigger a new final comment period. +- 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 'ready'. + +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 + +![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 'ready' implies +nothing about what priority is assigned to its implementation, nor whether +anybody is currently working on it. + +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 +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 +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 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). + +**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