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.



Stages overview

Name Entrance criteria This stage signifies Specification quality at entrance
Stage 0
  • That the proposer intends to use the stage process to work on their idea, with the goal of it landing in WHATWG Living Standard(s).
  • An explainer describing the problem to be solved, including sketching use cases and scenarios. This explainer can exist anywhere, including in a GitHub issue or a personal repository.
Stage 1
  • A comprehensive explainer for the Contribution, in a standards organization-approved incubation venue such as a W3C CG or a branch of an existing WHATWG Standard.
  • Consensus that the WHATWG is interested in exploring solutions in this problem space.
  • (At least) one implementer interested in doing prototyping work.
  • Identification of the Contributor.
  • Identification of a relevant WHATWG Workstream and Standard that will host the Contribution, and notification of the Workstream Editor(s).
  • Consensus that the problem is worth solving, and is within the scope of the WHATWG.
  • Commitment from the community to do work on the specification, which includes: review the specification and discussion about API improvements and adjustments.
  • The WHATWG commits to hosting a specification draft in a repository or branch (if the Contributor requests it).
Stage 2
  • A draft specification for the Contribution, in a standards organization-approved incubation venue (see stage 1).
  • Consensus that the rough API shape defined in the draft specification is the right approach to solve the problem, pending any significant problems found during this stage.
  • The WHATWG expects the Contribution to be developed and eventually included in the relevant WHATWG standard.
  • This stage also demonstrates commitment from the community to review the specification, and commitment from the Contributor to drive the addition of comprehensive tests, ideally with a prototype in at least one browser engine.
  • The draft specification uses Web IDL to define any new JavaScript APIs, roughly matches the style of the standard it's expected to merge into, and has a processing model, including full algorithms. However, there may be rough edges or TODOs in the processing model.
Stage 3
  • Complete specification text.
  • Support of at least two implementers to land the Contribution in the standard, pending editorial revisions.
  • During this stage, a PR to the relevant WHATWG Living Standard will be created.
  • The solution is complete and no further work is possible without implementation experience, significant usage and external feedback.
  • Any substantial design changes from the specification draft after reaching this stage should be highlighted in a way that gives all involved browser engines a chance to comment.
  • An Editor of the relevant WHATWG Living Standard will perform a full review of the pull request to add the Contribution, with an expectation of landing soon.
  • Specification is complete: all data structures, processing model, and API are fully described. (It may still have small issues that will be identified by editor review during this stage.)
  • Full specification and comprehensive tests are completed; pull request template is filled out with all checkboxes checked.
Stage 4
  • Editor’s comments on the pull request have all been resolved, and the pull request for the Contribution has been merged by the Editor.
  • The pull request has been approved to change a WHATWG Living Standard.
  • The Contribution is merged into the WHATWG Living Standard.