Documentation: Add RFCs process document

[aduth]

Closes #14926

This pull request seeks to add a document at docs/rfcs/README.md which adds basic information about the RFC process.

The text of the document pulls from:

• The original Make/Core blog post by @youknowriad describing the process
• Discussion from the 2019-05-15 #core-editor Meeting about RFC workflow momentum (link requires registration)

Some specific differences from the original blog post include:

• Marking RFC documents as "Draft" or "Standard"
• Proposing the use of a Requests for Comments (RFCs) project board
• A bit more explicitness around who's involved in various steps along the way

View Document

[chrisvanpatten]

I like this a lot, but maybe it makes more sense inside the contributor documentation (contributors) so it syncs over to DevHub too? (Unless we're planning to also sync the whole rfcs folder over, which I'm totally fine with too!)

[aduth]

I like this a lot, but maybe it makes more sense inside the contributor documentation (contributors) so it syncs over to DevHub too? (Unless we're planning to also sync the whole rfcs folder over, which I'm totally fine with too!)

@chrisvanpatten My expectation is that since existing proposals (and as outlined in the process) are to be merged as documents within docs/rfcs, this would serve as the base document for the folder. So to your specific question: Yes, this folder would contain documents of the RFCs themselves. I don't really have a strong opinion one way or the other as to whether they be included in DevHub, but they are quite specific to workflow of the project itself and, as much, not as relevant for user-facing (developer-facing) documentation.

[chrisvanpatten]

Perhaps then it's worth a page inside the contributor documentation, or at least a link to this markdown file, so we have some record of the RFC process within the contributor docs on DevHub? Perhaps somewhere under "Developer Contributions"?

I'm pretty agnostic about what that looks like, as long as it's referenced somewhere there for anyone browsing that handbook.

[karmatosed]

Overall this reads really clearly which I feel is the main goal. Great work @aduth. I have a few considerations:

• Maybe give some examples of other project's use of RFC or at least note that it's common practice there?
• It could be good to clearly outline the benefits of RFC's, I am not sure that's done here but I think just a little why could help encourage usage of this.
• When you say 'see examples' it could be good to clarify they are Gutenberg RFCs. I say this as overtime they could expand to core. I understand for now they are in the repo.
• Reading through I do feel a 'when' section is good and a 'why'.

[nerrad]

Great job here @aduth, I like the clarity this brings to the RFC process! I just have a few bits of feedback:

• Should there be any allowance here for RFC's that interact with core functionality in WordPress core and include component maintainers for those areas in WP core in the comment period?
• Related to the above, I am a bit concerned about the perception that decisions/progression on RFC's in the GB project supersede any process that may exist for what lands in WP core (being that the GB plugin serves as the source of what goes in WordPress core). So should there be clarification that RFC's for the Gutenberg project are only considered for things that fit within the identified focuses for GB as it relates to WordPress core releases? As a contrived example, how would a submitted RFC for replacing WordPress admin list tables be received in this project?
• Should there be a set defined time for comment period (i.e. no less than and no more than)?

[aduth]

Thanks for the feedback, y'all!

@chrisvanpatten :

Perhaps then it's worth a page inside the contributor documentation, or at least a link to this markdown file, so we have some record of the RFC process within the contributor docs on DevHub? Perhaps somewhere under "Developer Contributions"?

That sounds reasonable. I've added a link to the "Developer Contributions" document in e2fd7bc. Will the RFC process document automatically become included in the handbook, or are there steps I need to take to make sure it is?

@karmotosed :

Maybe give some examples of other project's use of RFC or at least note that it's common practice there?

That's a good idea. There were examples in the original blog post. I've included those in dc71c8c, plus a few others which can serve as further reference for the specific "stages" proposal (draft status).

It could be good to clearly outline the benefits of RFC's, I am not sure that's done here but I think just a little why could help encourage usage of this.

I've added a new section "Why have an RFC process?" in 33fb091.

When you say 'see examples' it could be good to clarify they are Gutenberg RFCs. I say this as overtime they could expand to core. I understand for now they are in the repo.

Clarified in 59b2f10.

To your latter point, I agree and I think it would be worth clarifying expectations of the role of this process with respect to decisions made in the project as a whole. My interpretation is that this entire process is an experiment intended to address concerns in the perceived lack of transparency with technical decision-making in WordPress 5.0, that the results of this experiment are yet to be seen, that the revisions to the original proposal here are to allow for results to be generated (currently blocked), and that, if successful, the process would be championed for adoption in the project at large. If this assessment is correct, I think it could be good to explain it as such in the document itself?

Reading through I do feel a 'when' section is good and a 'why'.

Can you clarify what you mean by "when"? Is "why" satisfied by the changes of 33fb091 ?

@nerrad :

Should there be any allowance here for RFC's that interact with core functionality in WordPress core and include component maintainers for those areas in WP core in the comment period?

This touches a bit on my previous remark about Gutenberg RFCs and core decision-making, but I totally expect that yes, component maintainers should be involved. In 51b844d , I've clarified this as an expectation for involved participants, including mention to solicit feedback (e.g. sharing in Slack channels).

Related to the above, I am a bit concerned about the perception that decisions/progression on RFC's in the GB project supersede any process that may exist for what lands in WP core (being that the GB plugin serves as the source of what goes in WordPress core). So should there be clarification that RFC's for the Gutenberg project are only considered for things that fit within the identified focuses for GB as it relates to WordPress core releases? As a contrived example, how would a submitted RFC for replacing WordPress admin list tables be received in this project?

This too follows my previous remark about RFCs and core. In the original blog post, there were some specific examples included for ideas of RFCs. I chose not to adapt them here, but perhaps they could help clarify some expectations around the sorts of features which would be applicable?

To your example, I think it's a matter of scoping, and in keeping RFCs more granular than to such a broad set of related features. This is my perception at least, reinforced by the original problem surfaced that existing RFCs may have become untenable in part due to their large scope. That said, as we've yet to merge a single RFC, there's not much evidence to support this one way or the other.

Should there be a set defined time for comment period (i.e. no less than and no more than)?

I think it would be good to be explicit to avoid the possibililty of stagnation, but I'm not sure what specific timeframe we should expect, or if it's a matter of timeframe vs. criteria for what should be considered a "sufficient baseline for an initial implementation". One benefit of a timeframe is that it sets clear, objective expectations around merges.

Do you have any suggestions for how this might be described?

[nerrad]

Do you have any suggestions for how this might be described?

Here's a suggestion:

The duration of an RFC period is a fine balance between providing enough time for stakeholders to participate and not so much time that the RFC stagnates. With that in mind, the RFC period will end no sooner than two weeks after the pull is published with a final deadline of 4 weeks after the pull is published to either merge or reject the RFC. For a merge of the RFC to occur, there must be the following pull approvals:

• Project Lead of Gutenberg at the time of the RFC
• At least two other Gutenberg Core team members
• At least one component maintainer for each of the affected components in WordPress core that the RFC impacts (a component maintainer may also satisfy the Gutenberg Core team requirement if they belong to that team).
• At least one person on the Gutenberg Core team with design expertise for RFC's impacting user facing interfaces.
• At least one person on the Gutenberg Core team with accessibility expertise for RFC's impacting user facing interfaces.

This is just to get the idea rolling but I do think the explicitness should include a cutoff date for making a decision as this gives people a clear idea of the timeline for participating in the comment period. Along with that, I think it is important to include what criteria are required for the RFC to be merged. RFC's should not be a "general community consensus" thing. They should welcome input from anyone, but ultimately, someone still has to make the decision.

I also wonder if we should have some limits on how many open RFC's there are at any one given time. While we welcome RFC's from anyone, there probably should be limits on how many are considered, especially if we set explicit durations for a comment period.

[aduth]

@nerrad This is great! I love the objectiveness of it toward the goals of making the process both clear and in pursuit of decisiveness.

A few notes:

• As you note in the text itself, timing is a fine balance. 2-4 weeks may need some adjustment, but it's a good place to start from.
• Should this in any way be made to align with weekly meetings? The existing proposal includes a mention "at least one weekly editor meeting" which may suffice.
• Does the timeframe account for statuses? Right now, we suffer from an initial merge of a draft upon which to start iteration. It's unclear whether it's this first merge that should be governed by a timeframe, or whether the entire proposal must be finalized in a given amount of time, which places a (maybe-necessary) pressure on implementations and iterations.

[aduth]

Worth noting that this sparked some discussion in the proposed Widgets RFC at #14812 (comment), which I've encouraged to direct here.

An interesting point raised there (and was also discussed in the original meeting discussion) was the verbiage around how we talk about this process. Even if we agree that "RFC" is not an inappropriate use of the word, it may be worth exploring an alternative which reduces the likelihood of early drafts being misinterpreted as final or otherwise not subject to change.

Possible alternatives, per my following comment:

• Standardization (as a "Stage"-based process)
• Recommendation (as a "Draft" and "Recommendation" process)

[nerrad]

The existing proposal includes a mention "at least one weekly editor meeting" which may suffice.

Yea that's why I said no less than two weeks because that should cover at least one weekly meeting. I think it'd be good to keep that criteria in.

Does the timeframe account for statuses? Right now, we suffer from an initial merge of a draft upon which to start iteration. It's unclear whether it's this first merge that should be governed by a timeframe, or whether the entire proposal must be finalized in a given amount of time, which places a (maybe-necessary) pressure on implementations and iterations.

I was considering what I wrote as the time frame for Draft status (at the end of which the RFC Draft) would be merged in if accepted. There may be some RFC's that are ready to merge in as draft after 2 weeks and others that go the full 4 weeks but I like the idea of having a definite ending date for making a decision on the RFC. I think it's completely acceptable if after 4 weeks have elapsed and the criteria has not been met to have those making the proposal take the feedback that has been given, identify the problem spaces, and submit a new RFC addressing the areas the first RFC had problems with. The process may also uncover places where the proposal can be split into smaller RFC's. To me it's crucial to understand that RFCs are generally intended to be for fairly significant project challenges/changes and as such it's not unreasonable to have more scrutiny on the proposals.

To be effective I think it'd also be good if the Draft RFC contains criteria identifying what is needed to be considered "feature complete" before it is accepted and merged as draft. Why?

• this will help with the eventual decision for when an RFC is ready to be given the "Standard" status.
• this will aid those providing feedback in the comment period with understanding what technical problems need iteration on before knowing which solutions to apply.
• It can aid with chunking problems into smaller sizes for solving.
• It can help with identifying expertise requirements for resolution.
• The above in turn can help with knowing who to specifically request feedback from in the general WordPress org.

I think having that as a part of the RFC requirements will help address some of the issues we've seen in our first two RFC experiments.

[nerrad]

Possible alternatives, per my following comment:

Standardization (as a "Stage"-based process)
Recommendation (as a "Draft" and "Recommendation" process)

While I'm still a fan of using something that is more familiar in the wider development world, I'm not opposed to coming up with different terminology for the WordPress project to use. However, I still think it's important to adopt something that is distinctive so when people see it they know what it means. So my suggestions are for something that works well both within GB and WP project (if this idea eventually gets adopted more widely): Press Change Draft, Press Change Final (or PCD and PCF)

[karmatosed]

Can you clarify what you mean by "when"? Is "why" satisfied by the changes of 33fb091 ?

Yes, this looks great to me now. I think it's good to get in and iterate from there. Thanks for all the work @aduth.

[mkaz]

A few minor suggestions around wording and tightening up.

[mkaz]

Minor edit for clarification

Suggested change

This process is both inspired and informed by other open source projects such as [React](https://github.com/reactjs/rfcs), [Yarn](https://github.com/yarnpkg/rfcs), and [Rust](https://github.com/rust-lang/rfcs), and of technical bodies standardization processes such as [IETF](https://tools.ietf.org/html/rfc2026), [W3C](https://www.w3.org/2004/02/Process-20040205/tr.html), and [TC39](https://tc39.github.io/process-document/).

The Gutenberg RFC process is inspired and informed by other open source projects such as [React](https://github.com/reactjs/rfcs), [Yarn](https://github.com/yarnpkg/rfcs), and [Rust](https://github.com/rust-lang/rfcs), and of technical bodies standardization processes such as [IETF](https://tools.ietf.org/html/rfc2026), [W3C](https://www.w3.org/2004/02/Process-20040205/tr.html), and [TC39](https://tc39.github.io/process-document/).

[mkaz]

Lead with what we are defining, not the why

Suggested change

	To maintain an effective and transparent process for resolving complex technical problems, this project has implemented a Request for Comments (RFC) workflow.
	The Gutenberg project uses a Request for Comments (RFC) workflow to maintain an effective and transparent process for resolving complex technical problems.

[mkaz]

Suggested change

	A document is final once its feature implementation is complete, and upon approval by focus leads.
	A document is final once its feature implementation is complete, and approved by focus leads.

[mkaz]

Tighten up a little, for example "refine details" and "revise specifics" are saying the same thing

Suggested change

A "Draft" document is one which has been merged in a state sufficient for initial implementations, but which is expected to need future iterations to refine details or revise specifics which would only become apparent in the course of said implementations. The purpose of allowing for draft documents is to allow for a steady momentum of a feature proposal and to embrace quality via experimentation.

A merged "Draft" document is sufficient for initial implementation, but expected to need future revisions based on details discovered during implementation. The purpose of allowing for draft documents is to allow for a steady momentum of a feature proposal and to embrace quality via experimentation.

[mkaz]

I believe this PR can be closed, the RFC process experiment was not successful, per Core Editor meeting on Nov 20, 2019