The WHATWG's approach to "documenting reality" is ideal for nailing down fundamental parts of the platform and improving interoperability and developer satisfaction. It can sometimes be daunting for new Contributors, who don't know how to reliably get implementer feedback or editor time commitment. The WHATWG Stages process is an optional, opt-in process that both new and established Contributors can use if they want to get more formal signals on support for their Contribution. This tool is generally used for medium-to-large Contributions; it's not expected to be used for each Contribution.
Stages asks for explicit implementer involvement at multiple checkpoints, starting from notification that the problem is being worked on, then sign-off on the rough API and specification, and finally agreement on the full specification text. These checkpoints are also useful to the broader community, helping web developers monitor the Contributions that are moving through the various stages. By explicitly signaling a Contribution's progress, including implementer involvement, the community has a better idea of what is going on in the WHATWG.
These checkpoints are modeled loosely on the TC39 process, which uses the concept of stages. Each subsequent stage implies a larger degree of consensus from the community, willingness to engage, implement, and eventually ship the feature in browser engines; and signals progress to web developers, drawing attention to incubations that have grown community support behind them.
- Stage: each successive stage is closer to an integrated Contribution and interoperable implementation. These stages are tracked on the issues in the relevant WHATWG GitHub repository, using labels ("stage 0", "stage 1", etc.). The stages are described in the Stages overview below.
- Browser engine: an independent implementation of the web platform (i.e., Chromium, Gecko, and WebKit at present).
- Implementation interest: a direct signal from a browser engine that a feature is on the roadmap to implement, as defined in the Working Mode].
- Browser engine representatives: persons delegated by a browser engine to indicate implementer interest.
- Any Contribution effectively starts at Stage 0 without any approvals, by a community member filing a new issue on a relevant WHATWG standard.
- It is expected that the Contributor will champion the Contribution, through answering questions asynchronously, providing feedback when requested, and consideration of important open questions at triage meetings.
- Anyone can review and submit feedback on Contributions.
- Stage level is tracked with labels on issues on the relevant standard — “stage 0”, “stage 1”, etc.
- Stage labels (other than stage 0) should only be added by browser engine representatives, or by Editors of the relevant standard, necessary support for a level has been demonstrated.
- This process is subject to and governed by WHATWG Policies, including the Intellectual Property Rights Policy.
- Advancing stages
- The Contributor should bring the Contribution to the WHATWG to advance to the next stage by setting an “Agenda+” label on the tracking issue, and showing up to (or ensuring someone will show up to) the next triage meeting to discuss. Advancing to a new stage requires support for the decision by at least two implementers (via their browser engine representatives), and there should not be any strong implementer objections (per the working mode. This support can also be gathered in any public manner, e.g., GitHub issue comments, triage meetings, etc.
- Positive support to advance a stage does not imply:
- Commitment to eventually support a subsequent stage.
- That the particular solution approach at the time of the signal or support will be the one eventually standardized (unless the advancement is to the Standardized stage).
- A negative response to advancing a stage does not imply:
- That the Contribution cannot continue in its current stage.
- That a future request for support to advance a stage with a revised solution won’t succeed.
- That all browsers will delay shipping the feature.
- That the feature cannot continue to be incubated outside of the WHATWG.
- A Contribution can advance directly to later stages without going through the earlier stages, if it's already mature enough and has sufficient support to do so.
- Regressing stages
- The browser engine representatives may review Contributions and decide to regress stages — for example, if implementer support has been retracted for a particular solution (regressing from stage 3 to stage 2), or even if support has been retracted for solving the problem (i.e., a regression from stage 2 to stage 1). This situation is expected to be unusual, and should come with a very strong justification.
| Name | Entrance criteria | This stage signifies | Specification quality at entrance |
|---|---|---|---|
| Stage 0 (Proposal) | — |
|
|
| Stage 1 (Incubation) |
|
|
|
| Stage 2 (Iteration) |
|
|
|
| Stage 3 (Committed) |
|
|
|
| Stage 4 (Standard) |
|
|
|