Skip to content

Commit cf89de4

Browse files
TrottTrott
committed
doc: introduce RFC process
Refs: nodejs/TSC#962
1 parent b560645 commit cf89de4

File tree

3 files changed

+297
-0
lines changed

3 files changed

+297
-0
lines changed

‎doc/rfcs/00000-rfc-process.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# RFC: RFC process
2+
3+
The request for comments (RFC) process is intended to provide a consistent and
4+
controlled path for new features to enter Node.js. The process helps find
5+
consensus among Node.js community and collaborators on substantial changes to
6+
the runtime.
7+
8+
## Motivation
9+
10+
Attempting to contribute substantial features to Node.js can result in
11+
interminable, chaotic, and repetitive conversations with no clear resolution and
12+
no realistic process for resolution. The intention of this proposal is to
13+
provide a clearer process.
14+
15+
Examples that may have benefited from an RFC process:
16+
17+
* [Implement window.fetch into core][]
18+
19+
## Guide-level explanation
20+
21+
You need to follow this process if you intend to make substantial changes to the
22+
Node.js runtime. Substantial changes include:
23+
24+
* Semantic or syntactic changes to Node.js that are not bugfixes.
25+
* Removing stable Node.js features.
26+
* New modules.
27+
* Bundling of new executables or removal of existing bundled executables.
28+
29+
Changes that do not require an RFC are changes that do not meet the preceding
30+
criteria. These might include:
31+
32+
* Rephrasing text or reorganizing documentation.
33+
* Refactoring code.
34+
* Bugfixes.
35+
* Changes that improve performance benchmarks.
36+
* Additions that only affect core developers and not end users.
37+
38+
If you submit a pull request to implement a new feature without going through
39+
the RFC process, it might be closed with a polite request to submit an RFC
40+
first.
41+
42+
## Reference-level explanation
43+
44+
To get a substantial feature added to Node.js, first get the RFC merged into the
45+
`rfcs` directory as a markdown file. At that point the RFC is _accepted_ and may
46+
be implemented with the goal of eventual inclusion into Node.js.
47+
48+
* Fork the RFC repo <https://github.com/nodejs/node>
49+
* Copy `doc/rfcs/00000-template.md` to `doc/rfcs/00000-my-feature.md` where
50+
`my-feature` is descriptive. Don't assign an RFC number yet.
51+
* Fill in the RFC.
52+
* Submit a pull request. The pull request is where we get review of the
53+
design from the larger community.
54+
* Once the pull request is opened, the submitter or a core team collaborator
55+
should:
56+
* Update the RFC file name to change `00000` to the pull request identifier.
57+
* Update `doc/rfcs/README.md` in the pull request to include the RFC in the
58+
[Accepted RFCs list][].
59+
* Build consensus and integrate feedback. RFCs that have broad support are much
60+
more likely to make progress than those that don't receive any comments.
61+
62+
Eventually, one of the [Node.js core team collaborators][] will either accept
63+
the RFC by merging the pull request, at which point the RFC is accepted, or
64+
reject it by closing the pull request.
65+
66+
Once an RFC becomes active then authors may implement it and submit the
67+
feature as a pull request to the Node.js repository. _Active_ is not a rubber
68+
stamp, and in particular still does not mean the feature will ultimately be
69+
merged. It does mean that in principle all the major stakeholders have agreed to
70+
the feature and are amenable to merging it.
71+
72+
Modifications to active RFCs can be done in subsequent PRs. An RFC that makes it
73+
through the entire process to implementation is _complete_ and is removed from
74+
the [Accepted RFCs List][].
75+
76+
## Drawbacks
77+
78+
* This approach means a formal process for substantial features where we do not
79+
currently have one. This could be seen as an advantage rather than drawback,
80+
Nonetheless, all else being equal, it is desirable to have less process. In an
81+
attempt to address this drawback, this proposal attempts a lightweight
82+
approach.
83+
84+
## Rationale and alternatives
85+
86+
The current process has resulted in a number of stalemates that have taken a
87+
toll on participants. It works well for bugfixes but not as well for big new
88+
features. Defining a process and reconsidering out decision-making process may
89+
avoid the problem, in the words of one contributor, of "Good ideas die because
90+
people can't agree on a parameter name."
91+
92+
Alternatives include:
93+
94+
* The _status quo_ may not be ideal, but perhaps it works well enough, or better
95+
than alternatives can be expected to work.
96+
* We could consider a more traditional heavyweight RFC process. There do not
97+
appear to be any advocates whatsoever for such a thing.
98+
* Instead (or in addition) to an RFC process, we could choose to expand and
99+
improve the Working Group (WG) model. This (arguably) worked well for ES
100+
modules. It is, however, harder to imagine it working well for deciding
101+
whether to implement fetch in Node.js core or whether to bundle package
102+
managers other than `npm`.
103+
104+
## Prior art
105+
106+
* [Node.js enhancement proposals][]
107+
* Only a few people wrote enhancement proposals (EPs). A bigger problem may
108+
have been that only a few people read them. One lesson this proposal tries
109+
to take from issues with the EP process is that the RFCs need to be visible.
110+
In general, Node.js information is overly siloed. Rather than placed in a
111+
separate repository, RFCs will live in the main Node.js core repository.
112+
* Because the process was, in effect, not mandatory, there were not a lot of
113+
examples by core team members showing what a good RFC and RFC process look
114+
like.
115+
* [Rust RFC process][]
116+
* This is largely what this proposal is modeled on.
117+
* [Python Enhancement Proposals][]
118+
* This is a more detailed (and thus heavyweight) model than what is proposed
119+
here.
120+
* [Any interest in an RFC process?][]
121+
* This TSC issue is what prompted this proposal. It contains more details
122+
about some background information that is summarized more briefly in this
123+
proposal.
124+
125+
## Unresolved questions
126+
127+
* This process should be implemented on a trial basis. What is the appropriate
128+
time period to evaluate how the RFC process is working? What is the process
129+
for that evaluation? How do we make changes or revoke the process? (TSC
130+
decision?)
131+
* Should RFCs (and other things perhaps) be consent-based rather than
132+
consensus-based?
133+
* Should RFC discussions be time-boxed? Getting to "no" faster would be good.
134+
It's not that the RFC process should lead to success all the time or even
135+
necessarily most of the time. It's that it should never lead to a years-long
136+
process which never arrives at a clear resolution one way or the other.
137+
* Should opening a pull request with a minimal implementation could be part of
138+
the process? This would fail to separate idea from implementation, but it
139+
would help people who feel they can't determine much with certainty until they
140+
see how it will be work in practice. (I'm hopeful that the emphasis on
141+
examples in the template will meet that need.)
142+
* How will this affect velocity? Is that a concern or out of scope?
143+
144+
[Accepted RFCs list]: ./README.md#accepted-rfcs-list
145+
[Any interest in an RFC process?]: https://github.com/nodejs/TSC/issues/962
146+
[Implement window.fetch into core]: https://github.com/nodejs/TSC/issues/962
147+
[Node.js core team collaborators]: ../../README.md#collaborators
148+
[Node.js enhancement proposals]: https://github.com/nodejs/node-eps
149+
[Python Enhancement Proposals]: https://www.python.org/dev/peps/pep-0001/
150+
[Rust RFC process]: https://github.com/rust-lang/rfcs/blob/HEAD/text/0002-rfc-process.md

‎doc/rfcs/00000-template.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# RFC: (name of feature)
2+
3+
One paragraph explanation of the feature.
4+
5+
## Motivation
6+
7+
Why are we doing this? What use cases does it support? What is the expected
8+
outcome?
9+
10+
## Guide-level explanation
11+
12+
Explain the proposal as if it was already included in the language and you were
13+
teaching it to another Node.js user.
14+
15+
* Introduce new named concepts.
16+
* Explain the feature largely in terms of examples.
17+
* Explain how Node.js users should think about the feature and how it might
18+
impact the way they use Node.js. It should explain the impact as concretely as
19+
possible.
20+
* If applicable, provide sample error messages, deprecation warnings, or
21+
migration guidance.
22+
23+
## Reference-level explanation
24+
25+
This is the technical portion of the RFC. Explain the design in detail.
26+
27+
* Explain its interaction with other features.
28+
* Explain how the would be implemented.
29+
* Explain edge cases with examples.
30+
31+
The section should return to the examples given in the previous section, and
32+
explain more fully how the detailed proposal makes those examples work.
33+
34+
## Drawbacks
35+
36+
Why might we *not* do this?
37+
38+
## Rationale and alternatives
39+
40+
The goal here is *not* be to promote the proposal by presenting it as
41+
favorably as possible. The goal is to explore options fairly and completely.
42+
43+
* Why is this design the best in the space of possible designs?
44+
* What other designs have been considered and what is the rationale for not
45+
choosing them?
46+
* What is the impact of not doing this?
47+
48+
## Prior art
49+
50+
Discuss prior art, both the good and the bad, in relation to this proposal.
51+
52+
* Does this feature exist in other programming languages? What experiences have
53+
their communities had and what lessons can we learn from them?
54+
* Are there any published papers, great posts, or other references that discuss
55+
this?
56+
57+
## Unresolved questions
58+
59+
* Perhaps you care about a particular feature, but do not have a specific
60+
proposal around certain details. This is the place to list those unresolved
61+
questions.
62+
* What related issues do you consider out of scope for this RFC that could be
63+
addressed in the future independently of the solution that comes out of this
64+
RFC?

‎doc/rfcs/README.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Node.js Core RFCs
2+
3+
The request for comments (RFC) process is intended to provide a consistent and
4+
controlled path for new features to enter Node.js. The process helps find
5+
consensus among Node.js community and collaborators on substantial changes to
6+
the runtime.
7+
8+
## Accepted RFCs list
9+
10+
There are no accepted RFCs yet.
11+
12+
## When you need to follow this process
13+
14+
You need to follow this process if you intend to make substantial changes to the
15+
Node.js runtime. Substantial changes include:
16+
17+
* Semantic or syntactic changes to Node.js that are not bugfixes.
18+
* Removing stable Node.js features.
19+
* New modules.
20+
* Bundling of new executables or removal of existing bundled executables.
21+
22+
Changes that do not require an RFC are changes that do not meet the preceding
23+
criteria. These might include:
24+
25+
* Rephrasing text or reorganizing documentation.
26+
* Refactoring code.
27+
* Bugfixes.
28+
* Changes that improve performance benchmarks.
29+
* Additions that only affect core developers and not end users.
30+
31+
If you submit a pull request to implement a new feature without going through
32+
the RFC process, it might be closed with a polite request to submit an RFC
33+
first.
34+
35+
## What the process is
36+
37+
To get a major feature added to Node.js, first get the RFC merged into the
38+
`rfcs` directory as a markdown file. At that point the RFC is _accepted_ and may
39+
be implemented with the goal of eventual inclusion into Node.js.
40+
41+
* Fork the RFC repo <https://github.com/nodejs/node>
42+
* Copy `doc/rfcs/00000-template.md` to `doc/rfcs/00000-my-feature.md` where
43+
`my-feature` is descriptive. Don't assign an RFC number yet.
44+
* Fill in the RFC.
45+
* Submit a pull request. The pull request is where we get review of the
46+
design from the larger community.
47+
* Once the pull request is opened, the submitter or a core team collaborator
48+
should:
49+
* Update the RFC file name to change `00000` to the pull request identifier.
50+
* Update `doc/rfcs/README.md` in the pull request to include the RFC in the
51+
[Accepted RFCs list][].
52+
* Build consensus and integrate feedback. RFCs that have broad support are much
53+
more likely to make progress than those that don't receive any comments.
54+
55+
Eventually, one of the [Node.js core team collaborators][] will either accept
56+
the RFC by merging the pull request, at which point the RFC is accepted, or
57+
reject it by closing the pull request.
58+
59+
Once an RFC becomes active then authors may implement it and submit the
60+
feature as a pull request to the Node.js repository. _Active_ is not a rubber
61+
stamp, and in particular still does not mean the feature will ultimately be
62+
merged. It does mean that in principle all the major stakeholders have agreed to
63+
the feature and are amenable to merging it.
64+
65+
Modifications to active RFCs can be done in subsequent PRs. An RFC that makes it
66+
through the entire process to implementation is _complete_ and is removed from
67+
the [Accepted RFCs List][].
68+
69+
## What the process tries to achieve
70+
71+
* Discourage unactionable or vague feature requests.
72+
* Ensure that all serious RFCs are considered equally.
73+
* Give confidence to those with a stake in Node.js development that they
74+
understand why new features are being merged.
75+
76+
## Acknowledgments
77+
78+
The initial proposal for this process is inspired by, modeled on, and partially
79+
copied from the [Rust RFC process][]
80+
81+
[Accepted RFCs list]: #accepted-rfcs-list
82+
[Node.js core team collaborators]: ../../README.md#collaborators
83+
[Rust RFC process]: https://github.com/rust-lang/rfcs/blob/HEAD/text/0002-rfc-process.md

0 commit comments

Comments
 (0)