Skip to content
This repository was archived by the owner on Aug 25, 2025. It is now read-only.

Commit ec5fdd7

Browse files
fitzgenfitzgen
authored
Merge pull request #1 from rustwasm/001-the-rfc-process
Propose an RFC process based on Rust's but lighter weight
2 parents 20c79d1 + ba05333 commit ec5fdd7

File tree

2 files changed

+286
-0
lines changed

2 files changed

+286
-0
lines changed

‎000-template.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
- Start Date: (fill me in with today's date, YYYY-MM-DD)
2+
- RFC PR: (leave this empty)
3+
- Tracking Issue: (leave this empty)
4+
5+
# Summary
6+
[summary]: #summary
7+
8+
One paragraph explanation of the proposal.
9+
10+
# Motivation
11+
[motivation]: #motivation
12+
13+
Why are we doing this? What use cases does it support? What problems does it
14+
solve? What is the expected outcome?
15+
16+
# Stakeholders
17+
[stakeholders]: #stakeholders
18+
19+
* Who is affected by this RFC?
20+
21+
* How are we soliciting feedback on this RFC from these stakeholders? Note that
22+
they may not be watching the RFCs repository or even aren't directly active in
23+
the Rust and WebAssembly working group.
24+
25+
# Detailed Explanation
26+
[detailed-explanation]: #detailed-explanation
27+
28+
- Introduce and explain new concepts.
29+
30+
- It should be reasonably clear how the proposal would be implemented.
31+
32+
- Provide representative examples that show how this proposal would be commonly
33+
used.
34+
35+
- Corner cases should be dissected by example.
36+
37+
# Drawbacks
38+
[drawbacks]: #drawbacks
39+
40+
- Why should we *not* do this?
41+
42+
# Rationale and Alternatives
43+
[alternatives]: #rationale-and-alternatives
44+
45+
This is your chance to discuss your proposal in the context of the whole design
46+
space. This is probably the most important section!
47+
48+
- Why is this design the best in the space of possible designs?
49+
50+
- What other designs have been considered and what is the rationale for not
51+
choosing them?
52+
53+
- What is the impact of not doing this?
54+
55+
# Unresolved Questions
56+
[unresolved]: #unresolved-questions
57+
58+
- What parts of the design do you expect to resolve through the RFC process
59+
before this gets merged?
60+
61+
- What parts of the design do you expect to resolve through the implementation
62+
of this feature?
63+
64+
- What related issues do you consider out of scope for this RFC that could be
65+
addressed in the future independently of the solution that comes out of this
66+
RFC?

‎text/001-the-rfc-process.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
- Start Date: 2018-06-28
2+
- RFC PR: (leave this empty)
3+
- Tracking Issue: (leave this empty)
4+
5+
# Summary
6+
[summary]: #summary
7+
8+
Adopt a simplified version of the Rust RFC process to the Rust and WebAssembly
9+
domain working group. The RFC process will provide a single place to decide on
10+
substantial changes and additions across the ecosystem for all stakeholders.
11+
12+
# Motivation
13+
[motivation]: #motivation
14+
15+
There are some decisions which have broad impact across the Rust and WebAssembly
16+
ecosystem, and therefore have many stakeholders who deserve to have a say in the
17+
decision and provide feedback on proposals and designs. Right now, these
18+
decisions tend to be made in whatever local repository pull request or issue
19+
tracker. This makes it difficult for stakeholders to stay on top of these
20+
decisions, because they need to watch many different places. For a repository
21+
owner or team, it is also difficult to determine whether the ecosystem is in
22+
favor of a feature or not.
23+
24+
After adopting this RFC process, stakeholders should have an easier time staying
25+
on top of substantial changes and features within the ecosystem. Additionally,
26+
the maintainers of a particular repository within the Rust and WebAssembly
27+
ecosystem should feel confident that they've solicited feedback from everyone
28+
involved after going through an RFC, and won't get angry bug reports from users
29+
who felt that they were not consulted. Everyone should have shared confidence in
30+
the direction that the ecosystem evolves in.
31+
32+
# Detailed Explanation
33+
[detailed-explanation]: #detailed-explanation
34+
35+
Right now, governance for repositories within the `rustwasm` organization
36+
[follow these rules][repo-governance] describing policy for merging pull
37+
requests:
38+
39+
> Unless otherwise noted, each `rustwasm/*` repository has the following general
40+
> policies:
41+
>
42+
> * All pull requests must be reviewed and approved of by at least one relevant
43+
> team member or repository collaborator before merging.
44+
>
45+
> * Larger, more nuanced decisions about design, architecture, breaking changes,
46+
> trade offs, etc are made by the relevant team and/or repository
47+
> collaborators consensus. In other words, decisions on things that aren't
48+
> straightforward improvements to or bug fixes for things that already exist
49+
> in the project.
50+
51+
This policy categorizes pull requests as either "larger, more nuanced ..."
52+
changes or not (we will use "substantial" from now on). When a change is not
53+
substantial, it requires only a single team member approve of it. When a change
54+
is larger and more substantial, then the relevant team comes to consensus on how
55+
to proceed.
56+
57+
This RFC intends to further sub-categorize substantial changes into those that
58+
affect only maintenance of the repository itself, and are therefore only
59+
substantial *internally* to the maintainers, versus those substantial changes
60+
that have an impact on *external* users and the larger Rust and WebAssembly
61+
community. For internally substantial changes, we do not intend to change the
62+
current policy at all. For substantial changes that have external impact, we
63+
will adopt a lightweight version of Rust's RFC process.
64+
65+
## When does a change need an RFC?
66+
67+
You need to follow the RFC process if you intend to make externally substantial
68+
changes to any repository within the [`rustwasm` organization][org], or the RFC
69+
process itself. What constitutes a "substantial" change is evolving based on
70+
community norms and varies depending on what part of the ecosystem you are
71+
proposing to change, but may include the following:
72+
73+
- The removal of or breaking changes to public APIs in widespread use.
74+
- Public API additions that extend the public API in new ways (i.e. more than
75+
"we implement `SomeTrait` for `ThisThing`, so also implement `SomeTrait` for
76+
`RelatedThing`").
77+
78+
Some changes do not require an RFC:
79+
80+
- Rephrasing, reorganizing, refactoring, or otherwise "changing shape does
81+
not change meaning".
82+
- Additions that strictly improve objective, numerical quality criteria
83+
(warning removal, speedup, better platform coverage, more parallelism, trap
84+
more errors, etc.)
85+
- Additions only likely to be _noticed by_ other maintainers, and remain
86+
invisible to users.
87+
88+
If you submit a pull request to implement a new feature without going through
89+
the RFC process, it may be closed with a polite request to submit an RFC first.
90+
91+
## The RFC process step by step
92+
93+
- Fork the [RFC repository][rfc-repo].
94+
- Copy `000-template.md` to `text/000-my-feature.md` (where "my-feature" is
95+
descriptive. Don't assign an RFC number yet).
96+
- Fill in the RFC. Put care into the details: RFCs that do not present
97+
convincing motivation, demonstrate understanding of the impact of the design,
98+
or are disingenuous about the drawbacks or alternatives tend to be
99+
poorly-received.
100+
- Submit a pull request. As a pull request, the RFC will receive design feedback
101+
from the larger community, and the author should be prepared to revise it in
102+
response.
103+
- Each new RFC pull request will be triaged in the next Rust and WebAssembly
104+
domain working group meeting and assigned to one or more of the [`@rustwasm/*`
105+
teams][teams].
106+
- Build consensus and integrate feedback. RFCs that have broad support are
107+
much more likely to make progress than those that don't receive any
108+
comments. Feel free to reach out to the RFC assignee in particular to get
109+
help identifying stakeholders and obstacles.
110+
- The team(s) will discuss the RFC pull request, as much as possible in the
111+
comment thread of the pull request itself. Offline discussion will be
112+
summarized on the pull request comment thread.
113+
- RFCs rarely go through this process unchanged, especially as alternatives
114+
and drawbacks are shown. You can make edits, big and small, to the RFC to
115+
clarify or change the design, but make changes as new commits to the pull
116+
request, and leave a comment on the pull request explaining your changes.
117+
Specifically, do not squash or rebase commits after they are visible on the
118+
pull request.
119+
- At some point, a member of the subteam will propose a "motion for final
120+
comment period" (FCP), along with a *disposition* for the RFC (merge, close,
121+
or postpone).
122+
- This step is taken when enough of the tradeoffs have been discussed that the
123+
team(s) are in a position to make a decision. That does not require
124+
consensus amongst all participants in the RFC thread (which may be
125+
impossible). However, the argument supporting the disposition on the RFC
126+
needs to have already been clearly articulated, and there should not be a
127+
strong consensus *against* that position outside of the team(s). Team
128+
members use their best judgment in taking this step, and the FCP itself
129+
ensures there is ample time and notification for stakeholders to push back
130+
if it is made prematurely.
131+
- For RFCs with lengthy discussion, the motion to FCP should be preceded by a
132+
*summary comment* trying to lay out the current state of the discussion and
133+
major tradeoffs/points of disagreement.
134+
- Before actually entering FCP, *all* members of the team(s) must sign off;
135+
this is often the point at which many team members first review the RFC in
136+
full depth.
137+
- The FCP lasts seven calendar days. It is also advertised widely, e.g. in an
138+
issue of ["This Week in Rust and WebAssembly" on the Rust and WebAssembly
139+
blog](https://rustwasm.github.io/). This way all stakeholders have a chance to
140+
lodge any final objections before a decision is reached.
141+
- In most cases, the FCP period is quiet, and the RFC is either merged or
142+
closed. However, sometimes substantial new arguments or ideas are raised,
143+
the FCP is canceled, and the RFC goes back into development mode.
144+
145+
## From RFC to implementation
146+
147+
Once an RFC is merged it becomes "active" then authors may implement it and
148+
submit the feature as a pull request to the relevant repositories. Being
149+
"active" is not a rubber stamp, and in particular still does not mean the
150+
feature will ultimately be merged; it does mean that in principle all the major
151+
stakeholders have agreed to the feature and are amenable to merging it.
152+
153+
Furthermore, the fact that a given RFC has been accepted and is "active" implies
154+
nothing about what priority is assigned to its implementation, nor does it imply
155+
anything about whether a developer has been assigned the task of implementing
156+
the feature. While it is not *necessary* that the author of the RFC also write
157+
the implementation, it is by far the most effective way to see an RFC through to
158+
completion: authors should not expect that other project developers will take on
159+
responsibility for implementing their accepted feature.
160+
161+
Modifications to "active" RFCs can be done in follow-up pull requests. We strive
162+
to write each RFC in a manner that it will reflect the final design of the
163+
feature; but the nature of the process means that we cannot expect every merged
164+
RFC to actually reflect what the end result will be at the time of the next
165+
major release.
166+
167+
In general, once accepted, RFCs should not be substantially changed. Only very
168+
minor changes should be submitted as amendments. More substantial changes should
169+
be new RFCs, with a note added to the original RFC.
170+
171+
# Rationale and Alternatives
172+
[alternatives]: #rationale-and-alternatives
173+
174+
The design space for decision making is very large, from democratic to
175+
autocratic and more.
176+
177+
Forking and simplifying Rust's RFC process is *practical*. Rather than designing
178+
a decision making process from scratch, we take an existing one that works well
179+
and tailor it to our needs. Many Rust and WebAssembly stakeholders are already
180+
familiar with it.
181+
182+
The main differences from the Rust RFC process are:
183+
184+
- FCP lasts seven calendar days rather than ten. This reflects our desire for a
185+
lighter-weight process that moves more quickly than Rust's RFC process.
186+
- The RFC template is shorter and merges together into single sections what were
187+
distinct sections in the Rust RFC template. Again, this reflects our desire
188+
for a lighter-weight process where we do not need to go into quite as much
189+
painstaking detail as Rust RFCs sometimes do (perhaps excluding *this* RFC).
190+
191+
The phases of RFC development and post-RFC implementation are largely the same
192+
as the Rust RFC process. We found that the motivations for nearly every phase of
193+
Rust's RFC process are equally motivating for the Rust and WebAssembly
194+
domain. We expected to simplify phases a lot, for example, we initially
195+
considered removing FCP and going straight to signing off on accepting an RFC or
196+
not. However, FCP exists as a way to (1) allow stakeholders to voice any final
197+
concerns that hadn't been brought up yet, and (2) help enforce the "no new
198+
rationale" rule. Both points apply equally well to the Rust and WebAssembly
199+
domain working group and ecosystem as they apply to Rust itself.
200+
201+
We can also avoid adopting an RFC process, and move more quickly by allowing
202+
each repository's team or owner to be dictators of their corner of the
203+
ecosystem. However, this will result in valuable feedback, opinions, and insight
204+
not getting voiced, and narrow decisions being made.
205+
206+
# Unresolved Questions
207+
[unresolved]: #unresolved-questions
208+
209+
- Will we use [`@rfcbot`][rfcbot]? If we can, we probably should, but this can
210+
be decided separately from whether to accept this RFC.
211+
212+
- How to best advertise new RFCs and FCP? Should we make "This Week in Rust and
213+
WebAssembly" actually be weekly rather than every other week? The interaction
214+
between FCP length and frequency of TWiRaWA posting seems important.
215+
216+
[rfcbot]: https://github.com/anp/rfcbot-rs
217+
[teams]: https://github.com/rustwasm/team/blob/master/GOVERNANCE.md#teams
218+
[org]: https://github.com/rustwasm
219+
[rfc-repo]: http://github.com/rustwasm/rfcs
220+
[repo-governance]: https://github.com/rustwasm/team/blob/master/GOVERNANCE.md#repositories

0 commit comments

Comments
 (0)