RFC 53: updates to RFC process

.github/ISSUE_TEMPLATE/tracking-issue.md

@@ -7,39 +7,35 @@ 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
+
+> See [RFC Process](https://github.com/aws/aws-cdk-rfcs#rfc-process) for details
 
 ## Workflow
 
 - [x] Tracking issue created (label: `status/proposed`)
-- [ ] Driver assigned
-- [ ] Approvers assigned
-- [ ] Stakeholders identified
+- [ ] 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)
+- [ ] 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.

.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
 
 ---
 

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
 

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,37 +176,56 @@ 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, 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.
+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
+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.
 
-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
 
@@ -216,7 +235,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 +260,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
+### 7. API Bar Raiser Sign-off
 
-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.
+Before you can merge your RFC, you will need the API Bar Raiser to sign off on
+the **Working Backwards** section of your document.
 
-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.
+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).
 
-### 8. Obtain final approval
+### 8. Final Comments Period
 
-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.
+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