From 4e783e33dadc467e53af6afe01425446401eec22 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel Date: Sun, 13 Jun 2021 12:41:30 +0300 Subject: [PATCH 01/15] Updates to RFC process As a follow up to a retrospective the CDK team has performed about the RFC process. This PR proposes the following changes: [ADD] --- .github/ISSUE_TEMPLATE/tracking-issue.md | 38 ++- README.md | 279 +++++++++++++---------- 2 files changed, 194 insertions(+), 123 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md index 8fd050e9c..5aaa3844f 100644 --- a/.github/ISSUE_TEMPLATE/tracking-issue.md +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -7,13 +7,39 @@ labels: management/tracking, status/proposed ## Description - +Short description of the proposed feature: +* First sentence describes the feature (think changelog entry) +* Describe the change to users as if it was already been implemented (i.e. like it would be described in the README). +* Add code or CLI commands as appropriate +* Keep it short -## Working Backwards +## Roles - +| Role | User +|---------------------|------------------------------ +| Proposed by | @alias +| Driver | @alias +| Approvers | @alias, @alias +| Stakeholders | @alias, @alias, @alias +| Implementation lead | @alias -## Roles +## Workflow + +- [x] Tracking issue created (label: `status/proposed`) +- [ ] Driver assigned +- [ ] Approvers assigned +- [ ] Stakeholders identified +- [ ] Kick off meeting +- [ ] RFC pull request created (label: `status/review`) +- [ ] Community reach out (via Slack and/or Twitter) +- [ ] Final comments period (label: `status/final-comments-period`) +- [ ] Approved and merged (label: `status/approved`) +- [ ] Implementation lead assigned +- [ ] Execution plan submitted (label: `status/planning`) +- [ ] Plan approved and merged (label: `status/implementing`) +- [ ] Implementation complete (label: `status/done`) + +--- -* **Driver** (drives the proposal to completion): @user -* **Approver(s)**: (assigned by CDK team) +> Driver is responsible drive the RFC according to this checklist, and apply the +relevant labels to this issue so that the RFC table in README gets updated. diff --git a/README.md b/README.md index 02dda5d3e..cdc706803 100644 --- a/README.md +++ b/README.md @@ -127,127 +127,172 @@ future state of the libraries and to discover projects for contribution. ## 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. - -## When to submit an RFC? - -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 +An RFC is a document that proposes a change to one of the projects led by the +CDK team at AWS. *Request for Comments* means a request for discussion and +oversight about the future of the project from maintainers, contributors and +users. + +**When to submit an RFC?** Anyone can submit an RFC for *any* change, big or +small, if they wish to obtain early feedback before they dive into +implementation. In some cases, especially for major features, the core team will +require that an RFC will be submitted. Quite often, even changes that seem +obvious and simple can be significantly improved once a wider group of +interested people have a chance to weigh in. + +> If you're not sure whether your change requires an RFC, feel free to create an issue and ask. ## RFC Process -In short, to get a major feature added to CDK/jsii, one usually writes an RFC -as a markdown file and gets it approved and merged into the RFC repo. At that point the RFC is -'approved' and may be implemented into CDK/jsii. - -1. [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. -2. Fork the [RFC repo](https://github.com/awslabs/aws-cdk-rfcs). -3. Copy `0000-template.md` to `text/-.md` where is the - tracking issue number and `` is the rfc title. -4. Fill in the RFC. Put care into the details: **We welcome all honest efforts - to contribute.**. -5. Submit a **pull request** with the title `RFC: ### ` where ### 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. -6. Update the tracking issue with a link to the RFC PR. -7. **Advertise** your RFC amongst stakeholders via social channels (e.g. - twitter) and your team. 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. -8. Eventually, the team will decide whether the RFC is a candidate for inclusion - in CDK/jsii. -9. 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. -10. An RFC can be modified based upon feedback from the team and community. - Significant modifications may trigger a new final comment period. An RFC can - also be modified after it has been merged and approved, in which case a new - PR will be submitted with the modification, like any other code. -11. 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 will then close the PR and issue. -12. 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 'approved'. -13. At some point, someone will pick up the RFC for implementation. For major - features this usually requires devising a detailed implementation plan. To - that end, submit an **additional PR** on the RFC doc that either fills in - the "Implementation Plan" section or references a separate document or - GitHub Project Board which includes the plan. -14. Once this PR is approved, the RFC will move to the 'implementing' state. - Usually we track implementation using GitHub projects. -15. Once implementation is complete, the RFC moves to 'done', and it's issue is - closed. - -> If the submitter is someone from our CDK community (i.e., not core team member), -a core team member will be assigned to 'shepherd' 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. -> -> On the other hand, if the submitter is a core team member, they will identify -another core team member, with consent, as their 'shepherd'. The shepherd would -be the first contact for brainstorming, process and reviews. The core team -would defer to the shepherd to do the first few rounds of reviews, after which -the rest of the team should be engaged. - -## RFC Life Cycle +To kick off an RFC process, simply create a [new tracking issue] and follow the instructions in the template. The issue includes a checklist of the various +stages an RFC goes through. + +This section describes each stage in detail, so you can refer to it for +guidance. + +### Create a tracking issue + +Each RFC has a GitHub issue that tracks it from start to finish. The issue is +the hub for conversations, community signal (+1s) and the issue number is used +as the unique identifier of this RFC. + +> Before creating a tracking issue, please search for similar or related ideas in +the RFC table above or in the issue list of this repo. If there is a relevant +RFC, collaborate on that existing RFC, based on its current stage. + +Our tracking issue template includes a checklist of all the steps an RFC goes +through and it's the driver's responsibility to update the checklist and assign +the correct label to on the RFC throughout the process. + +When the issue is created, it is required to fill in the following information: + +1. **Title**: the name of the feature or change - think changelog entry. +2. **Description**: a _short_ description of feature, as if it was already implemented. +3. **Proposed by**: fill in the GitHub alias of the person who proposed the idea + under "Proposed by". + +### Identify roles and responsibilities + +Each RFC has a __driver__, __approver(s)__ and __stakeholders__. + +The __driver__ is the person responsible to drive this RFC to completion. This +does __not__ mean that the driver must be the person actually doing all the +work, but it is the person responsible to get the RFC through the finish line. + +__Approvers__ are the people that have the authority to approve the RFC and any +subsequent changes to it. Approvers have the final word if we cannot reach +consensus. + +__Stakeholders__ are people (internal/external) who may be impacted by this RFC +or work on similar domains or projects. The goal is to make sure that +stakeholders have an opportunity to influence the direction of the RFC in +various stages of the process. + +The driver is responsible to update the **Roles** table in the tracking issue. + +### Organize a kick-off meeting + +Before diving into writing the RFC, is it highly recommended to organize a +kick-off meeting that includes the driver, approver(s) and stakeholders. The +goal of the meeting is to discuss the feature, its scope and general direction +for implementation. + +Our experience shows that such a meeting can save a lot of time and energy. + +Use the tracking issue to record any ideas and decisions from the kick-off +meeting and update the issue checklist to indicate that the kick-off meeting has +happened, + +### Write RFC document and implement prototype + +The next step is to write the first revision of the RFC document itself. + +**Document**: Use the file [0000-template.md](./0000-template.md) as a template +and put your new RFC under `text/NNNN-name.md` (where `NNNN` is your tracking +issue number). + +Follow the template. It includes useful guidance and tips on how to write a good RFC. + +**Prototype**: in many cases, it is useful to develop a prototype or even start +coding the actual implementation while you are writing the RFC document. Take +into account that you may need to throw your code away or refactor it +substantially, but our experience shows that good RFCs are the ones who dive +into the details. A prototype is great way to make sure your design "holds +water". + +Submit the RFC document as a pull request in this repo and start collecting +feedback. + +### Invite community to review + +The whole point of the RFC is to get feedback ("request for comments"). Once you +have an initial version submitted as a pull request, it is time to reach out to +the community and any relevant stakeholders and solicit their feedback. + +Use the [cdk.dev](https://cdk.dev) Slack workspace, Twitter and any other +relevant forum to publish your RFC and ask the community to provide their +feedback. + +### Iterate on the RFC document + +This is where the fun begins. Once you start receiving feedback on your pull request, +iterate on your document. Take time to read the comments, understand where people are coming +from, respond politely and iterate. + +A few tips: + +- If you decide to resolve a comment without addressing it, take the time to explain. +- Try to understand where people are coming from. If a comment seems off, ask folks to elaborate and + describe their use case or provide concrete examples. +- Work with your approver(s): if there are disagreements, @mention them in a comment and ask them + to provide their opinion. +- Be patient: it sometimes takes time for an RFC to converge. Our experience shows that some ideas + need to "bake" and solutions oftentimes emerge via a healthy debate. We've had RFCs that took + months to resolve. +- Not everything must be resolved in the first revision. It is okay to leave + some things to resolve later. Make sure to capture them clearly and have an + agreement about that. We oftentimes update an RFC doc a few times during the + implementation. + +### Final Comments Period + +At some point, you've reached consensus about most issues that were brought up +during the review period. In consultation with the approvers, a driver can +announce that the RFC enters "final comments period", which means that within a +~week, if no major concerns are raised, the RFC will be approved and merged. + +Add a comment on the RFC pull request and tracking issue that the RFC entered +this stage so that all relevant stakeholders will be notified. + +### Obtain final approval + +Once the final comments period is over, and the author has made final edits, the +RFC can be approved by the approvers and merged into the repository. + +NOTE: only RFCs that were approved by approvers should be merged. + +### Implement the new feature + +For large changes, we highly recommend creating an implementation plan which +lists all the tasks required. In many cases, large implementation should be +broken down and released via multiple iterations. Devising a concrete plan to +break down the break can be very helpful. + +The implementation plan should be submitted through a PR that adds an addendum +to the RFC document and seeks the approval of any relevant stakeholders. + +Throughout this process, update the tracking issue: + +- Add the alias of the "implementation lead" +- Execution plan submitted (label: `status/planning`) +- Plan approved and merged (label: `status/implementing`) +- Implementation complete (label: `status/done`) + +## State Diagram + +The following state diagram describes the RFC process: + +<a id="diagram"></a> ![rfc-states](./images/lifecycle.png) From 78499a4bacbeb04821e57210ef54504b593715ce Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Sun, 13 Jun 2021 14:22:12 +0300 Subject: [PATCH 02/15] Update 0000-template.md --- 0000-template.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/0000-template.md b/0000-template.md index d430f99ec..fc1ad0854 100644 --- a/0000-template.md +++ b/0000-template.md @@ -1,12 +1,13 @@ ---- -rfc pr: [#xxx](https://github.com/aws/aws-cdk-rfcs/pull/xxx) <-- fill this after you've already created the PR -tracking issue: https://github.com/aws/aws-cdk-rfcs/issues/yyy ---- - # [TITLE] > One sentence: brief description of the feature from a user perspective. +Administration: + +* Tracking issue: https://github.com/aws/aws-cdk-rfcs/issues/yyy +* Author(s): +* Approver(s): + ## Working Backwards > This section should contain one or more "artifacts from the future", as if the From 4f3f3ede71319145451d6f885c64245ec8eeefcf Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Sun, 13 Jun 2021 15:14:46 +0300 Subject: [PATCH 03/15] Soem template updates --- 0000-template.md | 70 +++++++++++++++++++++--------------------------- 1 file changed, 30 insertions(+), 40 deletions(-) diff --git a/0000-template.md b/0000-template.md index fc1ad0854..79dceca6d 100644 --- a/0000-template.md +++ b/0000-template.md @@ -2,52 +2,42 @@ > One sentence: brief description of the feature from a user perspective. -Administration: - * Tracking issue: https://github.com/aws/aws-cdk-rfcs/issues/yyy -* Author(s): -* Approver(s): +* Author(s): @alias, @alias, ... +* Approver(s): @alias, @alias, ... ## Working Backwards > This section should contain one or more "artifacts from the future", as if the -> feature was already released and we are publishing its CHANGELOG, README -> and optionally a PRESS RELEASE. -> -> This is the most important section of your RFC. It's a powerful thought -> exercise which will challenge you to truly think about this feature from a -> user's point of view. - -### CHANGELOG - -> Write the changelog entry for this feature in conventional form (e.g. -> `feat(eks): cluster tags`). -> -> If this change includes a breaking change, include a `BREAKING CHANGE` clause -> with information on how to migrate. If migration is complicated, refer to a -> fictional GitHub issue and add its contents here. - -### README - -> If this is a new feature, write the README section which describes this new -> feature. It should describe the feature and walk users through usage examples -> and description of the various options and behavior. - -### PRESS RELEASE - -> If this is a major feature (~6 months of work), write the PRESS RELEASE which -> announces this feature. The press release is a single page that includes 7 -> paragraphs: (1) summary, (2) problem, (3) solution, (4) leader quote, (5) user -> experience, (6) customer testimonial and (7) one sentence call to action. - -## FAQ - -> This section should contain answers to questions customers will likely ask about -> this release. Similar to the working backwards section, this section should be -> written "from the future" in a language as if the feature is now released. +> feature was already released and we are publishing its CHANGELOG, README and +> optionally a PRESS RELEASE. This is the most important section of your RFC. +> It's a powerful thought exercise which will challenge you to truly think about +> this feature from a user's point of view. + +> Choose *one or more* of the options below: +> * **CHANGELOG**: Write the changelog entry for this feature in conventional form +> (e.g. `feat(eks): cluster tags`). If this change includes a breaking change, +> include a `BREAKING CHANGE` clause with information on how to migrate. If +> migration is complicated, refer to a fictional GitHub issue and add its +> contents here. +> * **README**: If this is a new feature, write the README section which describes +> this new feature. It should describe the feature and walk users through usage +> examples and description of the various options and behavior. +> * **PRESS RELEASE**: If this is a major feature (~6 months of work), write the +> press release which announces this feature. The press release is a single page +> that includes 7 paragraphs: (1) summary, (2) problem, (3) solution, (4) leader +> quote, (5) user experience, (6) customer testimonial and (7) one sentence call +> to action. + +## Frequently Asked Questions + +> This section should include answers to questions readers will likely ask about +> this release. Similar to the "working backwards", this section should be +> written in a language as if the feature is now released. > -> The template includes a bunch of common questions, and you should add -> questions that might be relevant to this feature. +> The template includes a some common questions, feel free to add any questions +> that might be relevant to this feature or omit questions that you feel are not +> applicable. ### What are we launching today? From 9b48abe61b5bb1394dfafe420b51155221e078b0 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Sun, 13 Jun 2021 15:18:24 +0300 Subject: [PATCH 04/15] readme updates --- README.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index cdc706803..56c62680f 100644 --- a/README.md +++ b/README.md @@ -144,13 +144,16 @@ issue and ask. ## RFC Process -To kick off an RFC process, simply create a [new tracking issue] and follow the instructions in the template. The issue includes a checklist of the various +To kick off an RFC process, simply create a [new tracking issue] and follow the +instructions in the template. The issue includes a checklist of the various stages an RFC goes through. +[new tracking issue]: https://github.com/aws/aws-cdk-rfcs/issues/new?assignees=&labels=management%2Ftracking%2C+status%2Fproposed&template=tracking-issue.md&title=proposal+title + This section describes each stage in detail, so you can refer to it for guidance. -### Create a tracking issue +### 1. Create a tracking issue Each RFC has a GitHub issue that tracks it from start to finish. The issue is the hub for conversations, community signal (+1s) and the issue number is used @@ -160,10 +163,12 @@ as the unique identifier of this RFC. the RFC table above or in the issue list of this repo. If there is a relevant RFC, collaborate on that existing RFC, based on its current stage. -Our tracking issue template includes a checklist of all the steps an RFC goes +Our [tracking issue template] includes a checklist of all the steps an RFC goes through and it's the driver's responsibility to update the checklist and assign the correct label to on the RFC throughout the process. +[tracking issue template]: https://github.com/aws/aws-cdk-rfcs/blob/master/.github/ISSUE_TEMPLATE/tracking-issue.md + When the issue is created, it is required to fill in the following information: 1. **Title**: the name of the feature or change - think changelog entry. @@ -171,7 +176,7 @@ When the issue is created, it is required to fill in the following information: 3. **Proposed by**: fill in the GitHub alias of the person who proposed the idea under "Proposed by". -### Identify roles and responsibilities +### 2. Identify roles and responsibilities Each RFC has a __driver__, __approver(s)__ and __stakeholders__. @@ -190,7 +195,7 @@ various stages of the process. The driver is responsible to update the **Roles** table in the tracking issue. -### Organize a kick-off meeting +### 3. Organize a kick-off meeting Before diving into writing the RFC, is it highly recommended to organize a kick-off meeting that includes the driver, approver(s) and stakeholders. The @@ -203,7 +208,7 @@ Use the tracking issue to record any ideas and decisions from the kick-off meeting and update the issue checklist to indicate that the kick-off meeting has happened, -### Write RFC document and implement prototype +### 4. Write RFC document and implement prototype The next step is to write the first revision of the RFC document itself. @@ -223,7 +228,7 @@ water". Submit the RFC document as a pull request in this repo and start collecting feedback. -### Invite community to review +### 5. Invite community to review The whole point of the RFC is to get feedback ("request for comments"). Once you have an initial version submitted as a pull request, it is time to reach out to @@ -233,7 +238,7 @@ Use the [cdk.dev](https://cdk.dev) Slack workspace, Twitter and any other relevant forum to publish your RFC and ask the community to provide their feedback. -### Iterate on the RFC document +### 6. Iterate on the RFC document This is where the fun begins. Once you start receiving feedback on your pull request, iterate on your document. Take time to read the comments, understand where people are coming @@ -254,7 +259,7 @@ A few tips: agreement about that. We oftentimes update an RFC doc a few times during the implementation. -### Final Comments Period +### 7. Final Comments Period At some point, you've reached consensus about most issues that were brought up during the review period. In consultation with the approvers, a driver can @@ -264,14 +269,14 @@ announce that the RFC enters "final comments period", which means that within a Add a comment on the RFC pull request and tracking issue that the RFC entered this stage so that all relevant stakeholders will be notified. -### Obtain final approval +### 8. Obtain final approval Once the final comments period is over, and the author has made final edits, the RFC can be approved by the approvers and merged into the repository. NOTE: only RFCs that were approved by approvers should be merged. -### Implement the new feature +### 9. Implementation For large changes, we highly recommend creating an implementation plan which lists all the tasks required. In many cases, large implementation should be From 6ffacd55d9b14080b8ad8526011d0fb4f50b5307 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Sun, 13 Jun 2021 15:20:53 +0300 Subject: [PATCH 05/15] Update .github/ISSUE_TEMPLATE/tracking-issue.md --- .github/ISSUE_TEMPLATE/tracking-issue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md index 5aaa3844f..f508f7553 100644 --- a/.github/ISSUE_TEMPLATE/tracking-issue.md +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -41,5 +41,5 @@ Short description of the proposed feature: --- -> Driver is responsible drive the RFC according to this checklist, and apply the +> Driver is responsible to progress the RFC according to this checklist, and apply the relevant labels to this issue so that the RFC table in README gets updated. From d41ceefee7f4febf96ecaa60226d41ecba7c8d00 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Sun, 13 Jun 2021 16:15:54 +0300 Subject: [PATCH 06/15] fix lint issues --- 0000-template.md | 9 ++++++--- README.md | 10 ++++------ 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/0000-template.md b/0000-template.md index 79dceca6d..1f0ed8dbc 100644 --- a/0000-template.md +++ b/0000-template.md @@ -2,7 +2,7 @@ > One sentence: brief description of the feature from a user perspective. -* Tracking issue: https://github.com/aws/aws-cdk-rfcs/issues/yyy +* Tracking issue: [#NNN](https://github.com/aws/aws-cdk-rfcs/issues/NNN) * Author(s): @alias, @alias, ... * Approver(s): @alias, @alias, ... @@ -12,17 +12,20 @@ > feature was already released and we are publishing its CHANGELOG, README and > optionally a PRESS RELEASE. This is the most important section of your RFC. > It's a powerful thought exercise which will challenge you to truly think about -> this feature from a user's point of view. - +> this feature from a user's point of view. +> > Choose *one or more* of the options below: +> > * **CHANGELOG**: Write the changelog entry for this feature in conventional form > (e.g. `feat(eks): cluster tags`). If this change includes a breaking change, > include a `BREAKING CHANGE` clause with information on how to migrate. If > migration is complicated, refer to a fictional GitHub issue and add its > contents here. +> > * **README**: If this is a new feature, write the README section which describes > this new feature. It should describe the feature and walk users through usage > examples and description of the various options and behavior. +> > * **PRESS RELEASE**: If this is a major feature (~6 months of work), write the > press release which announces this feature. The press release is a single page > that includes 7 paragraphs: (1) summary, (2) problem, (3) solution, (4) leader diff --git a/README.md b/README.md index 56c62680f..fbe2a31d6 100644 --- a/README.md +++ b/README.md @@ -178,7 +178,7 @@ When the issue is created, it is required to fill in the following information: ### 2. Identify roles and responsibilities -Each RFC has a __driver__, __approver(s)__ and __stakeholders__. +Each RFC has a __driver__, __approver(s)__ and __stakeholders__. The __driver__ is the person responsible to drive this RFC to completion. This does __not__ mean that the driver must be the person actually doing all the @@ -210,7 +210,7 @@ happened, ### 4. Write RFC document and implement prototype -The next step is to write the first revision of the RFC document itself. +The next step is to write the first revision of the RFC document itself. **Document**: Use the file [0000-template.md](./0000-template.md) as a template and put your new RFC under `text/NNNN-name.md` (where `NNNN` is your tracking @@ -242,12 +242,12 @@ feedback. This is where the fun begins. Once you start receiving feedback on your pull request, iterate on your document. Take time to read the comments, understand where people are coming -from, respond politely and iterate. +from, respond politely and iterate. A few tips: - If you decide to resolve a comment without addressing it, take the time to explain. -- Try to understand where people are coming from. If a comment seems off, ask folks to elaborate and +- Try to understand where people are coming from. If a comment seems off, ask folks to elaborate and describe their use case or provide concrete examples. - Work with your approver(s): if there are disagreements, @mention them in a comment and ask them to provide their opinion. @@ -297,8 +297,6 @@ Throughout this process, update the tracking issue: The following state diagram describes the RFC process: -<a id="diagram"></a> - ![rfc-states](./images/lifecycle.png) <!-- From 6acf4b597c55ec1701696e841a19fe8da3d89003 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Fri, 18 Jun 2021 13:02:08 +0300 Subject: [PATCH 07/15] Update 0000-template.md Co-authored-by: Niranjan Jayakar <nija@amazon.com> --- 0000-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0000-template.md b/0000-template.md index 1f0ed8dbc..431151207 100644 --- a/0000-template.md +++ b/0000-template.md @@ -9,7 +9,7 @@ ## Working Backwards > This section should contain one or more "artifacts from the future", as if the -> feature was already released and we are publishing its CHANGELOG, README and +> feature was already released and we are publishing its CHANGELOG, README, CONTRIBUTING.md and > optionally a PRESS RELEASE. This is the most important section of your RFC. > It's a powerful thought exercise which will challenge you to truly think about > this feature from a user's point of view. From a775fa226985c25221f739f8702a4977f01000e7 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Fri, 18 Jun 2021 13:02:51 +0300 Subject: [PATCH 08/15] Update README.md Co-authored-by: Niranjan Jayakar <nija@amazon.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fbe2a31d6..b9bfea589 100644 --- a/README.md +++ b/README.md @@ -197,7 +197,7 @@ The driver is responsible to update the **Roles** table in the tracking issue. ### 3. Organize a kick-off meeting -Before diving into writing the RFC, is it highly recommended to organize a +Before diving into writing the RFC, it is highly recommended to organize a kick-off meeting that includes the driver, approver(s) and stakeholders. The goal of the meeting is to discuss the feature, its scope and general direction for implementation. From 7cf970e4fddb97ed38c71def13cb0b83c9fe54c3 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Thu, 24 Jun 2021 14:53:38 +0300 Subject: [PATCH 09/15] change approval model to focus on api bar raisers --- .github/ISSUE_TEMPLATE/tracking-issue.md | 22 ++--- .github/PULL_REQUEST_TEMPLATE.md | 5 +- 0000-template.md | 49 +++++----- README.md | 108 ++++++++++++++--------- 4 files changed, 106 insertions(+), 78 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md index f508f7553..c3050b13d 100644 --- a/.github/ISSUE_TEMPLATE/tracking-issue.md +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -7,39 +7,33 @@ labels: management/tracking, status/proposed ## Description -Short description of the proposed feature: -* First sentence describes the feature (think changelog entry) -* Describe the change to users as if it was already been implemented (i.e. like it would be described in the README). -* Add code or CLI commands as appropriate -* Keep it short +Short description of the proposed feature. ## Roles | Role | User |---------------------|------------------------------ | Proposed by | @alias -| Driver | @alias -| Approvers | @alias, @alias +| Author | @alias +| API Bar Raiser | @alias | Stakeholders | @alias, @alias, @alias -| Implementation lead | @alias ## Workflow - [x] Tracking issue created (label: `status/proposed`) -- [ ] Driver assigned -- [ ] Approvers assigned -- [ ] Stakeholders identified +- [ ] API Bar Raiser assigned - [ ] Kick off meeting - [ ] RFC pull request created (label: `status/review`) - [ ] Community reach out (via Slack and/or Twitter) +- [ ] API Bar Raiser signed-off - [ ] Final comments period (label: `status/final-comments-period`) - [ ] Approved and merged (label: `status/approved`) -- [ ] Implementation lead assigned - [ ] Execution plan submitted (label: `status/planning`) - [ ] Plan approved and merged (label: `status/implementing`) - [ ] Implementation complete (label: `status/done`) --- -> Driver is responsible to progress the RFC according to this checklist, and apply the -relevant labels to this issue so that the RFC table in README gets updated. +> Author is responsible to progress the RFC according to this checklist, and +apply the relevant labels to this issue so that the RFC table in README gets +updated. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index de6a3588a..23bca45be 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,5 +1,8 @@ -* Tracking issue: # +ONE-LINE DESCRIPTION (from TRACKING ISSUE) + +* Tracking issue: #NNN * [Rendered version](/my-branch/text/xxxx.md) +* API Bar Raiser: @user --- diff --git a/0000-template.md b/0000-template.md index 431151207..c0f49d8a1 100644 --- a/0000-template.md +++ b/0000-template.md @@ -1,36 +1,41 @@ -# [TITLE] +# [#NNN](http://github.com/aws/aws-cdk-rfcs/issues/NNN) [TITLE] -> One sentence: brief description of the feature from a user perspective. - -* Tracking issue: [#NNN](https://github.com/aws/aws-cdk-rfcs/issues/NNN) -* Author(s): @alias, @alias, ... -* Approver(s): @alias, @alias, ... +> Write one sentence which is a brief description of the feature from a user +> perspective ("impact on users"). ## Working Backwards > This section should contain one or more "artifacts from the future", as if the -> feature was already released and we are publishing its CHANGELOG, README, CONTRIBUTING.md and -> optionally a PRESS RELEASE. This is the most important section of your RFC. -> It's a powerful thought exercise which will challenge you to truly think about -> this feature from a user's point of view. +> feature was already released and we are publishing its CHANGELOG, README, +> CONTRIBUTING.md and optionally a PRESS RELEASE. This is the most important +> section of your RFC. It's a powerful thought exercise which will challenge you +> to truly think about this feature from a user's point of view. > > Choose *one or more* of the options below: > -> * **CHANGELOG**: Write the changelog entry for this feature in conventional form -> (e.g. `feat(eks): cluster tags`). If this change includes a breaking change, -> include a `BREAKING CHANGE` clause with information on how to migrate. If -> migration is complicated, refer to a fictional GitHub issue and add its -> contents here. +> * **CHANGELOG**: Write the changelog entry for this feature in conventional +> form (e.g. `feat(eks): cluster tags`). If this change includes a breaking +> change, include a `BREAKING CHANGE` clause with information on how to +> migrate. If migration is complicated, refer to a fictional GitHub issue and +> add its contents here. > -> * **README**: If this is a new feature, write the README section which describes -> this new feature. It should describe the feature and walk users through usage -> examples and description of the various options and behavior. +> * **README**: If this is a new feature, write the README section which +> describes this new feature. It should describe the feature and walk users +> through usage examples and description of the various options and behavior. > > * **PRESS RELEASE**: If this is a major feature (~6 months of work), write the -> press release which announces this feature. The press release is a single page -> that includes 7 paragraphs: (1) summary, (2) problem, (3) solution, (4) leader -> quote, (5) user experience, (6) customer testimonial and (7) one sentence call -> to action. +> press release which announces this feature. The press release is a single +> page that includes 7 paragraphs: (1) summary, (2) problem, (3) solution, (4) +> leader quote, (5) user experience, (6) customer testimonial and (7) one +> sentence call to action. + + + +> Once the API Bar Raiser signed-off on this RFC, tick the box below: + +``` +[ ] Signed-off by API Bar Raiser @xxxxx +``` ## Frequently Asked Questions diff --git a/README.md b/README.md index b9bfea589..ed14896e6 100644 --- a/README.md +++ b/README.md @@ -155,7 +155,7 @@ guidance. ### 1. Create a tracking issue -Each RFC has a GitHub issue that tracks it from start to finish. The issue is +Each RFC has a GitHub issue which tracks it from start to finish. The issue is the hub for conversations, community signal (+1s) and the issue number is used as the unique identifier of this RFC. @@ -176,31 +176,46 @@ When the issue is created, it is required to fill in the following information: 3. **Proposed by**: fill in the GitHub alias of the person who proposed the idea under "Proposed by". -### 2. Identify roles and responsibilities +### 2. API Bar Raiser -Each RFC has a __driver__, __approver(s)__ and __stakeholders__. +The public API of a feature represents the surface through which users interact +with it, and we want to make sure these APIs are consistent, ergonomic and +designed based on the intent and the mental model of our users. Additionally, +once we announce that a feature is "stable" (1.0, GA, etc) any breaking change +to its public API will require releasing a new major version, so we think of API +decisions as "one way doors". -The __driver__ is the person responsible to drive this RFC to completion. This -does __not__ mean that the driver must be the person actually doing all the -work, but it is the person responsible to get the RFC through the finish line. +For each RFC, the core team will assign an **API Bar Raiser** who reviews and +approves any public API of the feature. API Bar Raisers have veto rights on +API-related design decisions, such as naming, structure, options, CLI commands +and others. -__Approvers__ are the people that have the authority to approve the RFC and any -subsequent changes to it. Approvers have the final word if we cannot reach -consensus. +After an RFC is proposed, the core team will assign it an API Bar Raiser using a +tiering model generally based on the size of the user base that will likely get +exposed to the feature. As a general rule, the more "significant" the change is, +we will assign a bar raiser with a wider and longer-term context of the project. -__Stakeholders__ are people (internal/external) who may be impacted by this RFC -or work on similar domains or projects. The goal is to make sure that -stakeholders have an opportunity to influence the direction of the RFC in -various stages of the process. +API Bar Raisers are required to **sign off** on the **Working Backwards** +section of your RFC, so we encourage to engage with them early in the process to +make sure you are aligned on how the API should be designed. -The driver is responsible to update the **Roles** table in the tracking issue. +The API Bar Raiser is called out in the RFC tracking issue and in the RFC +document itself. Feel free to reach us at the +[#aws-cdk-rfcs](https://cdk-dev.slack.com/archives/C025ZFGMUCD) channel in the +[cdk.dev](https://cdk.dev) slack workspace if you need a bar raiser assigned to +your RFC. + +> The engineering solution proposed in an RFC does not need require approval +> beyond the normal pull request approval model (e.g. a core team member needs +> to approve the RFC PR and any subsequent changes to it). ### 3. Organize a kick-off meeting Before diving into writing the RFC, it is highly recommended to organize a -kick-off meeting that includes the driver, approver(s) and stakeholders. The -goal of the meeting is to discuss the feature, its scope and general direction -for implementation. +kick-off meeting that includes the API Bar Raiser and any stakeholders that +might be interested in this RFC or can contribute ideas and direction. The goal +of the meeting is to discuss the feature, its scope and general direction for +implementation. Our experience shows that such a meeting can save a lot of time and energy. @@ -216,7 +231,8 @@ The next step is to write the first revision of the RFC document itself. and put your new RFC under `text/NNNN-name.md` (where `NNNN` is your tracking issue number). -Follow the template. It includes useful guidance and tips on how to write a good RFC. +Follow the template. It includes useful guidance and tips on how to write a good +RFC. **Prototype**: in many cases, it is useful to develop a prototype or even start coding the actual implementation while you are writing the RFC document. Take @@ -240,41 +256,51 @@ feedback. ### 6. Iterate on the RFC document -This is where the fun begins. Once you start receiving feedback on your pull request, -iterate on your document. Take time to read the comments, understand where people are coming -from, respond politely and iterate. +This is where the fun begins. Once you start receiving feedback on your pull +request, iterate on your document. Take time to read the comments, understand +where people are coming from, respond politely and iterate. A few tips: -- If you decide to resolve a comment without addressing it, take the time to explain. -- Try to understand where people are coming from. If a comment seems off, ask folks to elaborate and - describe their use case or provide concrete examples. -- Work with your approver(s): if there are disagreements, @mention them in a comment and ask them - to provide their opinion. -- Be patient: it sometimes takes time for an RFC to converge. Our experience shows that some ideas - need to "bake" and solutions oftentimes emerge via a healthy debate. We've had RFCs that took - months to resolve. +- If you decide to resolve a comment without addressing it, take the time to + explain. +- Try to understand where people are coming from. If a comment seems off, ask + folks to elaborate and describe their use case or provide concrete examples. +- Work with your API bar raiser: if there are disagreements, @mention them in a + comment and ask them to provide their opinion. +- Be patient: it sometimes takes time for an RFC to converge. Our experience + shows that some ideas need to "bake" and solutions oftentimes emerge via a + healthy debate. We've had RFCs that took months to resolve. - Not everything must be resolved in the first revision. It is okay to leave some things to resolve later. Make sure to capture them clearly and have an agreement about that. We oftentimes update an RFC doc a few times during the implementation. -### 7. Final Comments Period - -At some point, you've reached consensus about most issues that were brought up -during the review period. In consultation with the approvers, a driver can -announce that the RFC enters "final comments period", which means that within a -~week, if no major concerns are raised, the RFC will be approved and merged. +### 7. API Bar Raiser Sign-off -Add a comment on the RFC pull request and tracking issue that the RFC entered -this stage so that all relevant stakeholders will be notified. +Before you can merge your RFC, you will need the API Bar Raiser to sign off on +the **Working Backwards** section of your document. -### 8. Obtain final approval +To record this sign-off, the bar raiser will add a comment to your RFC PR +indicating that the working backwards section looks good to them (LGTM) and will +update the RFC doc to check the "sign off" box in the working backwards section +(see template). -Once the final comments period is over, and the author has made final edits, the -RFC can be approved by the approvers and merged into the repository. +### 8. Final Comments Period -NOTE: only RFCs that were approved by approvers should be merged. +At some point, you've reached consensus about most issues that were brought up +during the review period, and you are ready to merge. To allow "last call" on +feedback, the author can announce that the RFC enters "final comments period", +which means that within a ~week, if no major concerns are raised, the RFC will +be approved and merged. + +Add a comment on the RFC pull request, tracking issue (and possibly slack/email +if relevant) that the RFC entered this stage so that all relevant stakeholders +will be notified. + +Once the final comments period is over, seek an approval of one of the core team +members, and you can merge your PR to the main branch. This will move your RFC +to the "approved" state. ### 9. Implementation From 5fa183f674c4fd448e4bae7914f45c949dca3bd1 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Thu, 24 Jun 2021 15:01:49 +0300 Subject: [PATCH 10/15] nija comments --- .github/ISSUE_TEMPLATE/tracking-issue.md | 4 +++- README.md | 10 +++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md index c3050b13d..7e19223ae 100644 --- a/.github/ISSUE_TEMPLATE/tracking-issue.md +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -18,10 +18,12 @@ Short description of the proposed feature. | API Bar Raiser | @alias | Stakeholders | @alias, @alias, @alias +> See [RFC Process](https://github.com/aws/aws-cdk-rfcs#rfc-process) for details + ## Workflow - [x] Tracking issue created (label: `status/proposed`) -- [ ] API Bar Raiser assigned +- [ ] API Bar Raiser assigned (ping us at [#aws-cdk-rfcs](https://cdk-dev.slack.com/archives/C025ZFGMUCD) if needed) - [ ] Kick off meeting - [ ] RFC pull request created (label: `status/review`) - [ ] Community reach out (via Slack and/or Twitter) diff --git a/README.md b/README.md index ed14896e6..c0a229ff6 100644 --- a/README.md +++ b/README.md @@ -219,9 +219,13 @@ implementation. Our experience shows that such a meeting can save a lot of time and energy. -Use the tracking issue to record any ideas and decisions from the kick-off -meeting and update the issue checklist to indicate that the kick-off meeting has -happened, +Use the RFC tracking issue to record some initial API and design ideas and +collect early feedback and use cases as a preparation for the kick off meeting. +You can start the meeting by letting participants obtaining context from the +tracking issue. + +At the end of the meeting, record any ideas and decisions in the tracking issue +and update the checklist to indicate that the kick-off meeting has happened. ### 4. Write RFC document and implement prototype From 1d7b5605580108bef063d6758d67285fda566b23 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Wed, 30 Jun 2021 15:32:04 +0300 Subject: [PATCH 11/15] Updates * Change RFC title not to include issue * Rephrase FAQ related to design * Multiple updates in README * Simplify PR template * Minor updates to tracking issue template --- .github/ISSUE_TEMPLATE/tracking-issue.md | 7 +- .github/PULL_REQUEST_TEMPLATE.md | 8 +- 0000-template.md | 12 +- README.md | 154 ++++++++++++----------- 4 files changed, 97 insertions(+), 84 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md index 7e19223ae..ff8932736 100644 --- a/.github/ISSUE_TEMPLATE/tracking-issue.md +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -23,11 +23,12 @@ Short description of the proposed feature. ## Workflow - [x] Tracking issue created (label: `status/proposed`) -- [ ] API Bar Raiser assigned (ping us at [#aws-cdk-rfcs](https://cdk-dev.slack.com/archives/C025ZFGMUCD) if needed) +- [ ] API bar raiser assigned (ping us at + [#aws-cdk-rfcs](https://cdk-dev.slack.com/archives/C025ZFGMUCD) if needed) - [ ] Kick off meeting -- [ ] RFC pull request created (label: `status/review`) +- [ ] RFC pull request submitted (label: `status/review`) - [ ] Community reach out (via Slack and/or Twitter) -- [ ] API Bar Raiser signed-off +- [ ] API signed-off (label `api-approved` applied to pull request) - [ ] Final comments period (label: `status/final-comments-period`) - [ ] Approved and merged (label: `status/approved`) - [ ] Execution plan submitted (label: `status/planning`) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 23bca45be..c85267143 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,10 +1,10 @@ -ONE-LINE DESCRIPTION (from TRACKING ISSUE) +This is a request for comments about {RFC_DESCRIPTION}. See #{TRACKING_ISSUE} for +additional details. -* Tracking issue: #NNN -* [Rendered version](/my-branch/text/xxxx.md) -* API Bar Raiser: @user +APIs are signed off by @{BAR_RAISER}. --- _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 c0f49d8a1..fb08e7293 100644 --- a/0000-template.md +++ b/0000-template.md @@ -1,4 +1,8 @@ -# [#NNN](http://github.com/aws/aws-cdk-rfcs/issues/NNN) [TITLE] +# {RFC_TITLE} + +* **Original Author:**: @{AUTHOR} +* **Tracking Issue**: #{TRACKING_ISSUE} +* **API Bar Raiser**: @{BAR_RAISER_USER} > Write one sentence which is a brief description of the feature from a user > perspective ("impact on users"). @@ -29,15 +33,13 @@ > leader quote, (5) user experience, (6) customer testimonial and (7) one > sentence call to action. - - > Once the API Bar Raiser signed-off on this RFC, tick the box below: ``` [ ] Signed-off by API Bar Raiser @xxxxx ``` -## Frequently Asked Questions +## Public FAQ > This section should include answers to questions readers will likely ask about > this release. Similar to the "working backwards", this section should be @@ -74,7 +76,7 @@ > Is there a way to address this use case with the current product? What are the > downsides of implementing this feature? -### What changes are required to enable this change? +### What is the technical solution (design) of this feature? > Briefly describe the high-level design approach for implementing this feature. > diff --git a/README.md b/README.md index c0a229ff6..04e5f8422 100644 --- a/README.md +++ b/README.md @@ -132,15 +132,21 @@ CDK team at AWS. *Request for Comments* means a request for discussion and oversight about the future of the project from maintainers, contributors and users. -**When to submit an RFC?** Anyone can submit an RFC for *any* change, big or -small, if they wish to obtain early feedback before they dive into -implementation. In some cases, especially for major features, the core team will -require that an RFC will be submitted. Quite often, even changes that seem -obvious and simple can be significantly improved once a wider group of -interested people have a chance to weigh in. - -> If you're not sure whether your change requires an RFC, feel free to create an -issue and ask. +**When should I write an RFC?** The CDK team proactively decides to write RFCs +on major features or complex changes that we feel require that extra vetting. +However, the process is designed to be as lightweight as needed and can be used +to request feedback on any change. Quite often, even changes that seem obvious +and simple at first sight can be significantly improved once a wider group of +interested and experienced people have a chance to weigh in. + +**Who should submit an RFC?** An RFC can be submitted by anyone. In most cases, +RFCs are authored by CDK maintainers, but contributors are more than welcome to +submit RFCs. + +If you are a **contributor** and you wish to write an RFC, please contact the +core team at the [#aws-cdk-rfcs] to make sure someone from the core team can +sponsor your work. Otherwise, there is a good chance we won't have bandwidth to +help. ## RFC Process @@ -153,7 +159,7 @@ stages an RFC goes through. This section describes each stage in detail, so you can refer to it for guidance. -### 1. Create a tracking issue +### 1. Tracking Issue Each RFC has a GitHub issue which tracks it from start to finish. The issue is the hub for conversations, community signal (+1s) and the issue number is used @@ -178,38 +184,34 @@ When the issue is created, it is required to fill in the following information: ### 2. API Bar Raiser +Reach us via [#aws-cdk-rfcs] to get an "API Bar Raiser" assigned to your RFC. + +For each RFC, CDK leadership will assign an **API Bar Raiser** who reviews and +approves the public API of the feature. API Bar Raisers have veto rights on +API-related design decisions, such as naming, structure, options, CLI commands +and others. + The public API of a feature represents the surface through which users interact with it, and we want to make sure these APIs are consistent, ergonomic and designed based on the intent and the mental model of our users. Additionally, once we announce that a feature is "stable" (1.0, GA, etc) any breaking change -to its public API will require releasing a new major version, so we think of API -decisions as "one way doors". - -For each RFC, the core team will assign an **API Bar Raiser** who reviews and -approves any public API of the feature. API Bar Raisers have veto rights on -API-related design decisions, such as naming, structure, options, CLI commands -and others. +to its public API will require releasing a new major version, so we like think +of API decisions as "one way doors". -After an RFC is proposed, the core team will assign it an API Bar Raiser using a -tiering model generally based on the size of the user base that will likely get -exposed to the feature. As a general rule, the more "significant" the change is, -we will assign a bar raiser with a wider and longer-term context of the project. +API Bar Raisers will be assigned using a tiering model which is generally based +on the size of the user base that will likely get exposed to the feature. As a +general rule, the more "significant" the feature is, we will assign a bar raiser +with a wider and longer-term context of the project. -API Bar Raisers are required to **sign off** on the **Working Backwards** -section of your RFC, so we encourage to engage with them early in the process to -make sure you are aligned on how the API should be designed. +To merge an RFC, a [sign-off](#6-api-sign-off) from the bar raiser is required +on the public API of the feature, so we encourage to engage with them early in +the process to make sure you are aligned on how the API should be designed. -The API Bar Raiser is called out in the RFC tracking issue and in the RFC -document itself. Feel free to reach us at the -[#aws-cdk-rfcs](https://cdk-dev.slack.com/archives/C025ZFGMUCD) channel in the -[cdk.dev](https://cdk.dev) slack workspace if you need a bar raiser assigned to -your RFC. - -> The engineering solution proposed in an RFC does not need require approval +> NOTE: The technical solution proposed in an RFC *does not* require approval > beyond the normal pull request approval model (e.g. a core team member needs > to approve the RFC PR and any subsequent changes to it). -### 3. Organize a kick-off meeting +### 3. Kick-off Before diving into writing the RFC, it is highly recommended to organize a kick-off meeting that includes the API Bar Raiser and any stakeholders that @@ -219,50 +221,50 @@ implementation. Our experience shows that such a meeting can save a lot of time and energy. -Use the RFC tracking issue to record some initial API and design ideas and -collect early feedback and use cases as a preparation for the kick off meeting. -You can start the meeting by letting participants obtaining context from the -tracking issue. +You can use the tracking issue to record some initial API and design ideas and +collect early feedback and use cases as a preparation for the kick-off meeting +and RFC document itself. You can start the meeting by letting participants +obtaining context from the tracking issue. At the end of the meeting, record any ideas and decisions in the tracking issue and update the checklist to indicate that the kick-off meeting has happened. -### 4. Write RFC document and implement prototype +### 4. RFC Document The next step is to write the first revision of the RFC document itself. -**Document**: Use the file [0000-template.md](./0000-template.md) as a template -and put your new RFC under `text/NNNN-name.md` (where `NNNN` is your tracking -issue number). - -Follow the template. It includes useful guidance and tips on how to write a good -RFC. - -**Prototype**: in many cases, it is useful to develop a prototype or even start -coding the actual implementation while you are writing the RFC document. Take -into account that you may need to throw your code away or refactor it -substantially, but our experience shows that good RFCs are the ones who dive -into the details. A prototype is great way to make sure your design "holds -water". +Create a file under `text/NNNN-name.md` based off of the template under +[`0000-template.md`](./0000-template.md) (where `NNNN` is your tracking issue +number). Follow the template. It includes useful guidance and tips on how to +write a good RFC. -Submit the RFC document as a pull request in this repo and start collecting -feedback. +**What should be included in an RFC?** The purpose of an RFC is to reduce +ambiguity and risk and get approval for public-facing interfaces (APIs), which +are "one-way doors" after the feature is released. Another way to think about it +is that the goal and contents of the document should allow us to create a +*high-confidence* implementation plan for a feature or a change. -### 5. Invite community to review +In many cases, it is useful to develop a **prototype** or even start coding the +actual implementation while you are writing the RFC document. Take into account +that you may need to throw your code away or refactor it substantially, but our +experience shows that good RFCs are the ones who dive into the details. A +prototype is great way to make sure your design "holds water". -The whole point of the RFC is to get feedback ("request for comments"). Once you -have an initial version submitted as a pull request, it is time to reach out to -the community and any relevant stakeholders and solicit their feedback. +### 5. Feedback -Use the [cdk.dev](https://cdk.dev) Slack workspace, Twitter and any other -relevant forum to publish your RFC and ask the community to provide their -feedback. +Once you have an initial version of your RFC document (it is completely fine to +submit an unfinished RFC to get initial feedback), submit it as a pull request +against this repo and start collecting feedback. -### 6. Iterate on the RFC document +Contact the CDK core team at [#aws-cdk-rfcs] (or via email/Slack if you are part +of the core team) and reach out to the public and Amazon internal communities +via various Slack channels in [cdk.dev](https://cdk.dev), Twitter and any other +relevant forum. -This is where the fun begins. Once you start receiving feedback on your pull -request, iterate on your document. Take time to read the comments, understand -where people are coming from, respond politely and iterate. +This is the likely going to be the longest part of your RFC process, and where +most of the feedback is collected. Some RFCs resolve quickly and some can take +months (!!). *Take into account at least 1-2 weeks to allow community and +stakeholders to provide their feedback.* A few tips: @@ -280,17 +282,23 @@ A few tips: agreement about that. We oftentimes update an RFC doc a few times during the implementation. -### 7. API Bar Raiser Sign-off +### 6. API Sign-off -Before you can merge your RFC, you will need the API Bar Raiser to sign off on -the **Working Backwards** section of your document. +Before you can merge your RFC, you will need the API Bar Raiser to sign-off on +the public API of your feature. This is will normally be described under the +**Working Backwards** section of your RFC. -To record this sign-off, the bar raiser will add a comment to your RFC PR -indicating that the working backwards section looks good to them (LGTM) and will -update the RFC doc to check the "sign off" box in the working backwards section -(see template). +To sign-off, the API bar raiser will add the **api-approved** label to the RFC +pull request. -### 8. Final Comments Period +Once the API was signed-off, update your RFC document and add a `[x]` the +relevant location in the RFC document. For example: + +``` +[x] Signed-off by API Bar Raiser @foobar +``` + +### 7. Final Comments Period At some point, you've reached consensus about most issues that were brought up during the review period, and you are ready to merge. To allow "last call" on @@ -306,7 +314,7 @@ Once the final comments period is over, seek an approval of one of the core team members, and you can merge your PR to the main branch. This will move your RFC to the "approved" state. -### 9. Implementation +### 8. Implementation For large changes, we highly recommend creating an implementation plan which lists all the tasks required. In many cases, large implementation should be @@ -385,3 +393,5 @@ RFC process], [React RFC process], and [Ember RFC process] [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 + +[#aws-cdk-rfcs]: https://cdk-dev.slack.com/archives/C025ZFGMUCD \ No newline at end of file From 0d6c91763a4b4eac4137082e18ba690584544e0c Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Wed, 30 Jun 2021 15:50:24 +0300 Subject: [PATCH 12/15] lint --- 0000-template.md | 4 +++- README.md | 6 +++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/0000-template.md b/0000-template.md index fb08e7293..df5dc4ee1 100644 --- a/0000-template.md +++ b/0000-template.md @@ -33,7 +33,9 @@ > leader quote, (5) user experience, (6) customer testimonial and (7) one > sentence call to action. -> Once the API Bar Raiser signed-off on this RFC, tick the box below: +Ticking the box below indicates that the public API of this RFC has been +signed-off by the API bar raiser (the `api-approved` label was applied to the +RFC pull request): ``` [ ] Signed-off by API Bar Raiser @xxxxx diff --git a/README.md b/README.md index 04e5f8422..cc256b212 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ interested and experienced people have a chance to weigh in. **Who should submit an RFC?** An RFC can be submitted by anyone. In most cases, RFCs are authored by CDK maintainers, but contributors are more than welcome to -submit RFCs. +submit RFCs. If you are a **contributor** and you wish to write an RFC, please contact the core team at the [#aws-cdk-rfcs] to make sure someone from the core team can @@ -189,7 +189,7 @@ Reach us via [#aws-cdk-rfcs] to get an "API Bar Raiser" assigned to your RFC. For each RFC, CDK leadership will assign an **API Bar Raiser** who reviews and approves the public API of the feature. API Bar Raisers have veto rights on API-related design decisions, such as naming, structure, options, CLI commands -and others. +and others. The public API of a feature represents the surface through which users interact with it, and we want to make sure these APIs are consistent, ergonomic and @@ -394,4 +394,4 @@ RFC process], [React RFC process], and [Ember RFC process] [react rfc process]: https://github.com/reactjs/rfcs [ember rfc process]: https://github.com/emberjs/rfcs -[#aws-cdk-rfcs]: https://cdk-dev.slack.com/archives/C025ZFGMUCD \ No newline at end of file +[#aws-cdk-rfcs]: https://cdk-dev.slack.com/archives/C025ZFGMUCD From 919ae4617f50dc6450c5ec570ef3b13006c1fda1 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Wed, 30 Jun 2021 17:21:26 +0300 Subject: [PATCH 13/15] Update .github/ISSUE_TEMPLATE/tracking-issue.md Co-authored-by: Romain Marcadier <rmuller@amazon.com> --- .github/ISSUE_TEMPLATE/tracking-issue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.md b/.github/ISSUE_TEMPLATE/tracking-issue.md index ff8932736..b86dd934f 100644 --- a/.github/ISSUE_TEMPLATE/tracking-issue.md +++ b/.github/ISSUE_TEMPLATE/tracking-issue.md @@ -14,7 +14,7 @@ Short description of the proposed feature. | Role | User |---------------------|------------------------------ | Proposed by | @alias -| Author | @alias +| Author(s) | @alias, @alias, @alias | API Bar Raiser | @alias | Stakeholders | @alias, @alias, @alias From e9bae64d2c35ce9854c90248b6fedb9bc4fbbce6 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Wed, 30 Jun 2021 17:21:31 +0300 Subject: [PATCH 14/15] Update 0000-template.md Co-authored-by: Romain Marcadier <rmuller@amazon.com> --- 0000-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0000-template.md b/0000-template.md index df5dc4ee1..f129038ff 100644 --- a/0000-template.md +++ b/0000-template.md @@ -1,6 +1,6 @@ # {RFC_TITLE} -* **Original Author:**: @{AUTHOR} +* **Original Author(s):**: @{AUTHOR} * **Tracking Issue**: #{TRACKING_ISSUE} * **API Bar Raiser**: @{BAR_RAISER_USER} From 2bd8b72bce1cd7c4d82d056f9abf5baffddf68e6 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel <benisrae@amazon.com> Date: Wed, 30 Jun 2021 17:23:48 +0300 Subject: [PATCH 15/15] Update README.md --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cc256b212..8308e6939 100644 --- a/README.md +++ b/README.md @@ -150,8 +150,8 @@ help. ## RFC Process -To kick off an RFC process, simply create a [new tracking issue] and follow the -instructions in the template. The issue includes a checklist of the various +To start an RFC process, create a [new tracking issue] and follow the +instructions in the issue template. It includes a checklist of the various stages an RFC goes through. [new tracking issue]: https://github.com/aws/aws-cdk-rfcs/issues/new?assignees=&labels=management%2Ftracking%2C+status%2Fproposed&template=tracking-issue.md&title=proposal+title @@ -219,6 +219,9 @@ might be interested in this RFC or can contribute ideas and direction. The goal of the meeting is to discuss the feature, its scope and general direction for implementation. +If you are not part of the CDK team at Amazon, reach out to us via [#aws-cdk-rfcs] +and we will help to organize the kick-off meeting. + Our experience shows that such a meeting can save a lot of time and energy. You can use the tracking issue to record some initial API and design ideas and