From cf89de4d61b4810d53d7515c4a4c3f63a2617be3 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 22 Mar 2021 13:32:41 -0700 Subject: [PATCH] doc: introduce RFC process Refs: https://github.com/nodejs/TSC/issues/962 --- doc/rfcs/00000-rfc-process.md | 150 ++++++++++++++++++++++++++++++++++ doc/rfcs/00000-template.md | 64 +++++++++++++++ doc/rfcs/README.md | 83 +++++++++++++++++++ 3 files changed, 297 insertions(+) create mode 100644 doc/rfcs/00000-rfc-process.md create mode 100644 doc/rfcs/00000-template.md create mode 100644 doc/rfcs/README.md diff --git a/doc/rfcs/00000-rfc-process.md b/doc/rfcs/00000-rfc-process.md new file mode 100644 index 00000000000000..a2742bddac3356 --- /dev/null +++ b/doc/rfcs/00000-rfc-process.md @@ -0,0 +1,150 @@ +# RFC: RFC process + +The request for comments (RFC) process is intended to provide a consistent and +controlled path for new features to enter Node.js. The process helps find +consensus among Node.js community and collaborators on substantial changes to +the runtime. + +## Motivation + +Attempting to contribute substantial features to Node.js can result in +interminable, chaotic, and repetitive conversations with no clear resolution and +no realistic process for resolution. The intention of this proposal is to +provide a clearer process. + +Examples that may have benefited from an RFC process: + +* [Implement window.fetch into core][] + +## Guide-level explanation + +You need to follow this process if you intend to make substantial changes to the +Node.js runtime. Substantial changes include: + +* Semantic or syntactic changes to Node.js that are not bugfixes. +* Removing stable Node.js features. +* New modules. +* Bundling of new executables or removal of existing bundled executables. + +Changes that do not require an RFC are changes that do not meet the preceding +criteria. These might include: + +* Rephrasing text or reorganizing documentation. +* Refactoring code. +* Bugfixes. +* Changes that improve performance benchmarks. +* Additions that only affect core developers and not end users. + +If you submit a pull request to implement a new feature without going through +the RFC process, it might be closed with a polite request to submit an RFC +first. + +## Reference-level explanation + +To get a substantial feature added to Node.js, first get the RFC merged into the +`rfcs` directory as a markdown file. At that point the RFC is _accepted_ and may +be implemented with the goal of eventual inclusion into Node.js. + +* Fork the RFC repo +* Copy `doc/rfcs/00000-template.md` to `doc/rfcs/00000-my-feature.md` where + `my-feature` is descriptive. Don't assign an RFC number yet. +* Fill in the RFC. +* Submit a pull request. The pull request is where we get review of the +design from the larger community. +* Once the pull request is opened, the submitter or a core team collaborator + should: + * Update the RFC file name to change `00000` to the pull request identifier. + * Update `doc/rfcs/README.md` in the pull request to include the RFC in the + [Accepted RFCs list][]. +* Build consensus and integrate feedback. RFCs that have broad support are much +more likely to make progress than those that don't receive any comments. + +Eventually, one of the [Node.js core team collaborators][] will either accept +the RFC by merging the pull request, at which point the RFC is accepted, or +reject it by closing the pull request. + +Once an RFC becomes active then authors may implement it and submit the +feature as a pull request to the Node.js repository. _Active_ is not a rubber +stamp, and in particular still does not mean the feature will ultimately be +merged. It does mean that in principle all the major stakeholders have agreed to +the feature and are amenable to merging it. + +Modifications to active RFCs can be done in subsequent PRs. An RFC that makes it +through the entire process to implementation is _complete_ and is removed from +the [Accepted RFCs List][]. + +## Drawbacks + +* This approach means a formal process for substantial features where we do not + currently have one. This could be seen as an advantage rather than drawback, + Nonetheless, all else being equal, it is desirable to have less process. In an + attempt to address this drawback, this proposal attempts a lightweight + approach. + +## Rationale and alternatives + +The current process has resulted in a number of stalemates that have taken a +toll on participants. It works well for bugfixes but not as well for big new +features. Defining a process and reconsidering out decision-making process may +avoid the problem, in the words of one contributor, of "Good ideas die because +people can't agree on a parameter name." + +Alternatives include: + +* The _status quo_ may not be ideal, but perhaps it works well enough, or better + than alternatives can be expected to work. +* We could consider a more traditional heavyweight RFC process. There do not + appear to be any advocates whatsoever for such a thing. +* Instead (or in addition) to an RFC process, we could choose to expand and + improve the Working Group (WG) model. This (arguably) worked well for ES + modules. It is, however, harder to imagine it working well for deciding + whether to implement fetch in Node.js core or whether to bundle package + managers other than `npm`. + +## Prior art + +* [Node.js enhancement proposals][] + * Only a few people wrote enhancement proposals (EPs). A bigger problem may + have been that only a few people read them. One lesson this proposal tries + to take from issues with the EP process is that the RFCs need to be visible. + In general, Node.js information is overly siloed. Rather than placed in a + separate repository, RFCs will live in the main Node.js core repository. + * Because the process was, in effect, not mandatory, there were not a lot of + examples by core team members showing what a good RFC and RFC process look + like. +* [Rust RFC process][] + * This is largely what this proposal is modeled on. +* [Python Enhancement Proposals][] + * This is a more detailed (and thus heavyweight) model than what is proposed + here. +* [Any interest in an RFC process?][] + * This TSC issue is what prompted this proposal. It contains more details + about some background information that is summarized more briefly in this + proposal. + +## Unresolved questions + +* This process should be implemented on a trial basis. What is the appropriate + time period to evaluate how the RFC process is working? What is the process + for that evaluation? How do we make changes or revoke the process? (TSC + decision?) +* Should RFCs (and other things perhaps) be consent-based rather than + consensus-based? +* Should RFC discussions be time-boxed? Getting to "no" faster would be good. + It's not that the RFC process should lead to success all the time or even + necessarily most of the time. It's that it should never lead to a years-long + process which never arrives at a clear resolution one way or the other. +* Should opening a pull request with a minimal implementation could be part of + the process? This would fail to separate idea from implementation, but it + would help people who feel they can't determine much with certainty until they + see how it will be work in practice. (I'm hopeful that the emphasis on + examples in the template will meet that need.) +* How will this affect velocity? Is that a concern or out of scope? + +[Accepted RFCs list]: ./README.md#accepted-rfcs-list +[Any interest in an RFC process?]: https://github.com/nodejs/TSC/issues/962 +[Implement window.fetch into core]: https://github.com/nodejs/TSC/issues/962 +[Node.js core team collaborators]: ../../README.md#collaborators +[Node.js enhancement proposals]: https://github.com/nodejs/node-eps +[Python Enhancement Proposals]: https://www.python.org/dev/peps/pep-0001/ +[Rust RFC process]: https://github.com/rust-lang/rfcs/blob/HEAD/text/0002-rfc-process.md diff --git a/doc/rfcs/00000-template.md b/doc/rfcs/00000-template.md new file mode 100644 index 00000000000000..d7e1c28948f5ff --- /dev/null +++ b/doc/rfcs/00000-template.md @@ -0,0 +1,64 @@ +# RFC: (name of feature) + +One paragraph explanation of the feature. + +## Motivation + +Why are we doing this? What use cases does it support? What is the expected +outcome? + +## Guide-level explanation + +Explain the proposal as if it was already included in the language and you were +teaching it to another Node.js user. + +* Introduce new named concepts. +* Explain the feature largely in terms of examples. +* Explain how Node.js users should think about the feature and how it might + impact the way they use Node.js. It should explain the impact as concretely as + possible. +* If applicable, provide sample error messages, deprecation warnings, or + migration guidance. + +## Reference-level explanation + +This is the technical portion of the RFC. Explain the design in detail. + +* Explain its interaction with other features. +* Explain how the would be implemented. +* Explain edge cases with examples. + +The section should return to the examples given in the previous section, and +explain more fully how the detailed proposal makes those examples work. + +## Drawbacks + +Why might we *not* do this? + +## Rationale and alternatives + +The goal here is *not* be to promote the proposal by presenting it as +favorably as possible. The goal is to explore options fairly and completely. + +* Why is this design the best in the space of possible designs? +* What other designs have been considered and what is the rationale for not + choosing them? +* What is the impact of not doing this? + +## Prior art + +Discuss prior art, both the good and the bad, in relation to this proposal. + +* Does this feature exist in other programming languages? What experiences have + their communities had and what lessons can we learn from them? +* Are there any published papers, great posts, or other references that discuss + this? + +## Unresolved questions + +* Perhaps you care about a particular feature, but do not have a specific + proposal around certain details. This is the place to list those unresolved + questions. +* What related issues do you consider out of scope for this RFC that could be + addressed in the future independently of the solution that comes out of this + RFC? diff --git a/doc/rfcs/README.md b/doc/rfcs/README.md new file mode 100644 index 00000000000000..9c310e2cb5471e --- /dev/null +++ b/doc/rfcs/README.md @@ -0,0 +1,83 @@ +# Node.js Core RFCs + +The request for comments (RFC) process is intended to provide a consistent and +controlled path for new features to enter Node.js. The process helps find +consensus among Node.js community and collaborators on substantial changes to +the runtime. + +## Accepted RFCs list + +There are no accepted RFCs yet. + +## When you need to follow this process + +You need to follow this process if you intend to make substantial changes to the +Node.js runtime. Substantial changes include: + +* Semantic or syntactic changes to Node.js that are not bugfixes. +* Removing stable Node.js features. +* New modules. +* Bundling of new executables or removal of existing bundled executables. + +Changes that do not require an RFC are changes that do not meet the preceding +criteria. These might include: + +* Rephrasing text or reorganizing documentation. +* Refactoring code. +* Bugfixes. +* Changes that improve performance benchmarks. +* Additions that only affect core developers and not end users. + +If you submit a pull request to implement a new feature without going through +the RFC process, it might be closed with a polite request to submit an RFC +first. + +## What the process is + +To get a major feature added to Node.js, first get the RFC merged into the +`rfcs` directory as a markdown file. At that point the RFC is _accepted_ and may +be implemented with the goal of eventual inclusion into Node.js. + +* Fork the RFC repo +* Copy `doc/rfcs/00000-template.md` to `doc/rfcs/00000-my-feature.md` where + `my-feature` is descriptive. Don't assign an RFC number yet. +* Fill in the RFC. +* Submit a pull request. The pull request is where we get review of the +design from the larger community. +* Once the pull request is opened, the submitter or a core team collaborator + should: + * Update the RFC file name to change `00000` to the pull request identifier. + * Update `doc/rfcs/README.md` in the pull request to include the RFC in the + [Accepted RFCs list][]. +* Build consensus and integrate feedback. RFCs that have broad support are much +more likely to make progress than those that don't receive any comments. + +Eventually, one of the [Node.js core team collaborators][] will either accept +the RFC by merging the pull request, at which point the RFC is accepted, or +reject it by closing the pull request. + +Once an RFC becomes active then authors may implement it and submit the +feature as a pull request to the Node.js repository. _Active_ is not a rubber +stamp, and in particular still does not mean the feature will ultimately be +merged. It does mean that in principle all the major stakeholders have agreed to +the feature and are amenable to merging it. + +Modifications to active RFCs can be done in subsequent PRs. An RFC that makes it +through the entire process to implementation is _complete_ and is removed from +the [Accepted RFCs List][]. + +## What the process tries to achieve + +* Discourage unactionable or vague feature requests. +* Ensure that all serious RFCs are considered equally. +* Give confidence to those with a stake in Node.js development that they + understand why new features are being merged. + +## Acknowledgments + +The initial proposal for this process is inspired by, modeled on, and partially +copied from the [Rust RFC process][] + +[Accepted RFCs list]: #accepted-rfcs-list +[Node.js core team collaborators]: ../../README.md#collaborators +[Rust RFC process]: https://github.com/rust-lang/rfcs/blob/HEAD/text/0002-rfc-process.md