Skip to content

Commit 3a63ab9

Browse files
flagxorflagxor
committed
Adding a document describing the phases through which a proposal will pass.
1 parent d108dca commit 3a63ab9

File tree

2 files changed

+194
-10
lines changed

2 files changed

+194
-10
lines changed

‎2017/CG-08-08.md

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,6 @@ The meeting will be a Google Hangouts call.
3030
1. Mailing list reshuffling:
3131
- public-webassembly is now for discussions, requires signup.
3232
- public-webassembly-announce is moderated and low-traffic, auto-signs up all CG members.
33-
<<<<<<< HEAD
3433
1. Discuss timing of next in person CG meeting.
3534
1. Hold these video calls regularly? What schedule? (JF Bastien)
3635
1. WebAssembly Working Group (Brad Nelson)
@@ -108,15 +107,6 @@ The meeting will be a Google Hangouts call.
108107
1. Bulk Memory Instructions (Ben Smith)
109108
1. [WIP proposal](https://gist.github.com/binji/acc43b94c0a747e51dfafa1b5b099c9a)
110109
1. Some initial performance numbers
111-
=======
112-
1. TBD
113-
1. Content Security Policy and WASM
114-
1. Coordinating spec tests with WebPlatformTests
115-
1. Presentation on JavaScript/HTML modules integration as stage-setting for wasm/HTML modules integration (Domenic Denicola)
116-
1. WebAssembly Working Group.
117-
1. Formation and logistics.
118-
1. Discussion on meeting times.
119-
>>>>>>> Add WG items.
120110
1. Closure
121111

122112
### Schedule constraints

‎process/phases.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# WebAssembly W3C Process
2+
3+
This file describes how feature proposals will progress through
4+
the standardization process.
5+
6+
A feature is a substantial change to WebAssembly, such that it for example
7+
requires additional opcodes, types, tests, or module sections.
8+
See case #3 [here](consensus.md).
9+
10+
Something is definitely a feature if it:
11+
* Adds an opcode or other pieces of abstract syntax
12+
* Changes or extends the binary format
13+
* Changes or extends the text format
14+
* Requires adding or changing tests
15+
* Requires extending or changing the reference interpreter
16+
17+
In general, the process moves forward through a series of numbered phases.
18+
However, if issues are uncovered or consensus devolves,
19+
proposals should back up to the appropriate prior step.
20+
21+
## 0. Pre-Proposal [Community Group]
22+
23+
Entry requirements:
24+
* A Community Group member has an idea.
25+
26+
During this phase an issue issue is filed to track a feature idea.
27+
Discussion on the feature occurs.
28+
A champion or champions emerge.
29+
At a point where a written proposal is useful to ground the discussion
30+
of the feature, a new repository is requested.
31+
32+
## 1. Feature Proposal [Community Group]
33+
34+
Entry requirements:
35+
* A Community Group member requests a repository in which to develop a
36+
feature.
37+
38+
During this phase a new repository forking the spec repo is created (Community
39+
Group members can request this). PRs + Issues iterate on the design of the
40+
feature.
41+
If a high level descriptions in a design repo style .md files is useful,
42+
these are added to describe the feature as it's being designed.
43+
A [tracking](https://github.com/WebAssembly/design/labels/tracking)
44+
issue is created in the design repo.
45+
46+
If relevant to demonstrate the viability of a feature, prototype
47+
implementations of the feature are implemented in interested embedders (possibly
48+
on a branch).
49+
The Community Group will attempt to reach broad consensus.
50+
51+
## 2. Proposed Spec Text Available [Community + Working Group]
52+
53+
Entry requirements:
54+
* Full proposed English spec text available in a forked repo around which a
55+
reasonably high level of consensus exists.
56+
* *Updates to the formal notation, test suite,
57+
and reference interpreter are NOT yet required*.
58+
59+
During this phase:
60+
* One or more implementations proceed on prototyping the
61+
feature to the point that a comprehensive set of tests can be added.
62+
* A test suite is added.
63+
These tests need not pass the reference interpreter at this point,
64+
but should pass on some implementation.
65+
66+
## 3. Implementation Phase [Community + Working Group]
67+
68+
Entry requirements:
69+
* Test suite has been updated to cover the feature in its forked repo.
70+
* The test suite should run against some implementation, though it need not be
71+
the reference interpreter.
72+
* *Formal notation in the spec need not be updated.*
73+
74+
During this phase, the following proceeds in parallel:
75+
* Embedders implement the feature.
76+
* The forked repo is updated to include revisions to the formalization.
77+
* The forked repo spec is updated to include implementation of the feature
78+
in the reference interpreter (OCaml).
79+
* The feature is implemented in toolchains.
80+
81+
## 4. Standardize the Feature [Working Group]
82+
83+
Entry requirements:
84+
* Two or more Web VMs implement the feature.
85+
* At least one toolchain implements the feature.
86+
* The formalization and the OCaml reference interpreter are usually updated
87+
(though these two can be done as part of step 3 at the Working Group
88+
chair's discretion).
89+
* Community Group has reached consensus in support of the feature.
90+
* NOTE: By this point the proposal is basically frozen,
91+
the Community Group is the sole venue where substantial work can occur.
92+
93+
At this point:
94+
* The feature is fully handed off to the Working Group.
95+
* During this phase, Working Group members discuss the feature,
96+
consider edge cases, and work to confirm consensus that the feature is now
97+
complete.
98+
* Only minor cosmetic changes occur at this point.
99+
If substantial changes are deemed required, the feature is sent back to
100+
the Community Group.
101+
102+
## 5. The Feature is Standardized [Working Group]
103+
104+
Entry requirements:
105+
* Consensus is reached in amongst Working Group members that the feature
106+
is complete.
107+
108+
When Working Group consensus is reached (online), editors can merge the feature
109+
into master on the spec repo.
110+
The W3C snapshots (for REC) are made at a regular cadence (in a W3C repo), used
111+
to stamp official version. Matching tags are added in the github spec repo.
112+
113+
114+
## Example how this might work
115+
116+
### Worker based Threads
117+
118+
0. Feature Proposal
119+
* Someone proposes adding threads to WebAssembly.
120+
* They file an issue to discuss this possibility.
121+
* Discussion continues and a champion for the feature emerges.
122+
* A request is made to add a threads proposal fork of the spec.
123+
124+
1. Feature Proposal
125+
* A threads repo is created: https://github.com/WebAssembly/threads
126+
* Once a human readable .md is agreed on describing behavior + opcodes,
127+
work to update the spec's English text to reflect the change in a branch
128+
occurs.
129+
A few browsers begin to prototype atomic opcodes behind flag to demonstrate
130+
feasibility.
131+
2. Proposed Spec Text Available
132+
* The Working Group is informed of the thrads proposal.
133+
* The proposed spec text is finalized describing the new opcodes for atomics,
134+
memory model, etc.
135+
* A test suite exercising threads is created. All the prototype
136+
implementations can run it.
137+
3. Implementation Phase
138+
* Work progresses to implement the agree opcodes for atomics in several
139+
browsers.
140+
* The OCaml interpreter is updated to simulate threads.
141+
* The formal language in the spec is expanded to describe atomics and the
142+
memory model.
143+
4. Standardized the Feature
144+
* The Working Group examines the spec, looking for edge cases, testing gaps,
145+
and unforseen interactions with other standards.
146+
* Everything is in order.
147+
5. The Feature is Standardized
148+
* Working Group member consensus is reached (potentially by distributed means).
149+
* Editors merge the spec changes from the branch to master on the spec repo.
150+
* Browsers turn on atomic ops by default.
151+
* Profit!
152+
153+
## FAQ
154+
155+
#### Who owns the various existing W3C repos?
156+
157+
They are owned in common by the Working + Community Groups. The Working Group
158+
uses the github.com/WebAssembly/spec repo to iterate on finalized proposals
159+
for hand-off
160+
to the W3C's snapshotted copy of the spec. The other repos are primarily
161+
overseen by the Community Group.
162+
163+
#### What about licenses?
164+
165+
The spec and spec forks will move to a
166+
[W3C Software and Document Notice and
167+
License](https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document).
168+
Other related repos for prototypes + tools will continue under their respective
169+
licenses.
170+
171+
#### What is the Community Group for?
172+
173+
Incubation.
174+
To provide a safe harbor for a broad set of stakeholders to discuss, design,
175+
and iterate on new features during Steps 1-3 above.
176+
It should attempt to address all concerns, but need not reach 100% consensus.
177+
178+
#### What is the Working Group for?
179+
180+
To finalize and ratify mostly complete specs + test suites from the Community
181+
Group.
182+
Changes to the spec need not have reached full consensus in the Community Group
183+
to move to the Working Group, but key Working Group stakeholders should resolve
184+
outstanding mismatch in the Community Group.
185+
186+
#### Who will have admin rights + close issues etc?
187+
188+
This can be distributed and handled by multiple folks.
189+
In terms of github issues specifically, chairs will mainly step in to drive
190+
consensus, keep discussions civil, and as a first escalation point if someone
191+
is unhappy with how the collaboration is conducted (for instance if someone is
192+
unhappy a particular issue was closed over their objections).
193+
This is a general part of their role in community building:
194+
https://www.w3.org/Guide/chair-roles

0 commit comments

Comments
 (0)