RFC: 0016 RFC Process

[MrArnoldPalmer]

Notes

These were put together using a combination of the React and Rust RFC process documents. Please suggest any additions or changes we think we should incorporate for our own process. As the readme says, the process is intentionally compromising as to allow for some organic evolution.

• Still need good examples of "Prior Art". The react RFC template doesn't include this section but I'm partial to it so I've kept it in. I want to get the teams feedback on whether we think this is something we should include. Removed prior art for now in favor of a more "react" style document that is less procedural and a little more broad. We can revisit this later as I believe it may prove useful for things like spec definition.
• I formatted these documents using prettier. I vote that we add a basic style guide, possibly even a package.json with tools/scripts we use to format and otherwise automatically verify the content of RFCs. This can be done separately if the team desires and could be useful if we write some automation of initial feedback using github actions or travis. Rust's RFC repo includes a styleguide and recommendations to use a formatting tool.
• Rust RFC project has a bot that creates a gitbook with active RFCs https://rfcbot.rs/, something to consider maybe?
• Should we define a pull request template and labels (e.g. "final comment period", "needs review", etc). PR and tracking issue templates are included.

Rendered

---

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache-2.0 license

[RomainMuller]

There's a lot of very CDK-centric language here - and most of it is fine, but as we're also using this for jsii, I think we should be less specific in any places... For example, in the template, there is:

• enough detail for somebody familiar with CDK to understand

• the impact on teaching people how to use CDK

• cost of migrating existing CDK applications

---

It's great you've dropped an Apache-2.0 license file. It lacks the corresponding NOTICE file that our standards demand is present... And it'd be dope to also drop the standard CODE_OF_CONDUCT.md file in there, too.

[RomainMuller]

Well we shouldn't be doing this at all (breach of semver)

[MrArnoldPalmer]

Should we change this to "deprecation of existing features or public APIs."? or just remove this line altogether?

I'm not sure how this breaks semver? It would just require a major version bump no?

[RomainMuller]

In the general case, yes...In certain specific cases, probably deserves an RFC. The case is for example for those complex services with an embedded DSL or document language (API Gateway, ECS, EKS, ...) where the CDK API would aim to simplify the user experience and that is effectively "interesting" (read: complex enough) API design.

[eladb]

Good point. If the API design is non-trivial, it's probably worth

[RomainMuller]

1. how about we make this into a front-matter (those render specially in GitHub, and I feel like it's a good fit)

   ---
   name: <unique identifier>
   date: <YYYY-MM-DD>
   pr: <pr-id-once-assigned>
   issue: <issue-id-once-assigned>
   ---
   

2. I'd like to encourage people to cross-reference RFCs, like an RFC may be an extension of another, may replace another, etc...

[eladb]

A few things that come to mind:

• This is a bit too external-facing. I feel like we need to integrate the internal RFC process into this.
• How do we allocate a shepherd for RFCs? Is that based on the ownership areas? What about stuff that doesn't fall under a specific ownership? Is this part of the support workflow?
• How does this integrate with our public roadmap? What's the prioritization process for RFCs we want to work on as a core team? Eventually I think these RFCs are going to be the main feed of our quarterly planning, so we need to make sure that we have a backlog of "ready to implement" RFCs (is that "active"?) so we can pick ones for squad implementation every quarter.
• Public/private - I have no doubt that we will eventually have some RFCs that we don't feel comfortable exposing publicly (e.g. internal support for CDK etc). Where do we handle/manage them?

[eladb]

Do we want these to be <!-- comments --> so it's clear they are just instructions?

[rix0rrr]

What is the problem with just replacing the text?

[eladb]

I find it easier to work on the doc in pieces and it wrapping the guidelines with <!-- comments --> make it simpler to tell which sections I've already filled in.

[MrArnoldPalmer]

The only thing that I worry about is not being able to easily read the template when rendered in the browser. My guess is that people will be reviewing the contents of the template on github before cloning the repo and working on it. I'm still open to this if you think its better with that in mind.

[eladb]

Fair enough, so how about using a block quote (>) for the guidelines?

Like this

[eladb]

I am a bit confused by the terminology of "active". doesn't "active" mean that it was already merged?

[rix0rrr]

I think active means "under discussion" ?

[MrArnoldPalmer]

"active" in rust/react's RFC process means, the RFC PR has been merged and it is ready for someone to work on implementation.

It looks like they also use the term "active" to refer to RFCs that are being discussed and haven't been merged. My vote is we change that to "Pending". So this would say "Pending RFC List".

Alternatively, we can change RFCs that have been merged and are ready to implement to be called "Resolved". That may connote too much finality though and may falsely indicate that the feature has been implemented already. Either way we should come up with nice simple names for the states for RFCs.

How about:

1. Pending - RFC PR is created and under review
2. Final Comment Period - RFC has been reviewed and is open for final comments before acceptance.
3. Active - RFC PR has been accepted and merged, ready for someone to implement.
4. Resolved - Implementation is done.

We may or may not want to have the "resolved" state/label. Are we going to come back to the RFC repo and resolve RFCs once implementations are finished?

[NetaNir]

I would say we should split 1 to:

1. Pending - waiting for a review
2. Under review - currently being reviewed

To reflect the team/community engagement in the RFC repo.

[eladb]

I am good with what you proposed, albeit those are not 100% intuitive to me (particularly “active” which has multiple intuitive connotations), but I see the value in using terminology close to existing projects.

I’d also like to formalize the state of projects that are still in the “idea” stage. Those will only have an issue with motivation in them but no RFC yet. For example, most of the issues we have in the repo right now are at this stage, and I think it will be super powerful to make them discoverable.

The beginning of the README should have a list of query links that will be easy to find all tracking issues for RFCs in each state.

[eladb]

Other examples:

• Changes to core team workflows
• Features that cross the construct-library
• Framework capabilities
• Formal specifications (like the cloud assembly, tree.json, etc).

[rix0rrr]

What is the problem with just replacing the text?

[rix0rrr]

I feel prior art should go before the proposed solution.

[rix0rrr]

I think active means "under discussion" ?

[NetaNir]

If I'm understanding correctly we will have a separate repo for RFCs that will host RFC's in all stages: pending , under review, final comments and active. One desired outcome of such repo will be that active RFCs will be picked up by the community. In order to appeal to wider audience I suggest that the repo README will have a short intro which explains RFC's, how are they created and how will the process of implementing an RFC looks like - emphasizing that a CDK team member will shepherd the process and will supply guidance and technical mentorship. The purpose of such intro is to avoid making the RFC implementation process intimidating and to encourage the community to participate. While I like the use of the formal RFC terminology I think we could benefit from loosening it a bit.

[NetaNir]

I would say we should split 1 to:

1. Pending - waiting for a review
2. Under review - currently being reviewed

To reflect the team/community engagement in the RFC repo.

[NetaNir]

Adding a reference to an existing 'good' RFC could be helpful

[eladb]

I think @NetaNir has an interesting point. In addition to managing the RFC process, I agree that we want this repo and process to be a place where community can discover ideas for CDK and jsii-related projects to contribute. It's related to my comment about an additional "idea" stage and a quick link to a query that people can use to find ideas, and I really like @NetaNir's idea to add "T shirt size estimation" to each RFC, so people can discover ideas in different levels of complexity.

Also, there's a point about the "RFC" terminology that might not be familiar to many people (in the CDK community), and so I agree that it makes sense to make it a bit more accessible and have less of a bureaucratic feel to it by lightning the language a little.

[MrArnoldPalmer]

I'm onboard with an intro section and lightening it up. As far as sizing goes we can create some labels and the core team shepherd can provide a rough estimate after implementation issues are created. We can also create a "good first project" label or something along those lines.

[eladb]

Nit: I think the title of this RFC should be "RFC Process" and not "Define RFC Process", no?

[eladb]

Fair enough, so how about using a block quote (>) for the guidelines?

Like this

[eladb]

YASS!

[eladb]

Horray! From: Mitchell Valine <[email protected]> Reply-To: awslabs/aws-cdk-rfcs <[email protected]> Date: Wednesday, 8 January 2020 at 18:48 To: awslabs/aws-cdk-rfcs <[email protected]> Cc: "Ben-israel, Elad" <[email protected]>, Mention <[email protected]> Subject: Re: [awslabs/aws-cdk-rfcs] RFC: #16 RFC Process (#53) Merged #53<#53> into master. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#53>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAESGDCP4FIQWS7JZ5F5B63Q4X7R3ANCNFSM4J4D6STQ>.