Specification Acceptance Stages

[cwilso]

This is a proposal for a new optional, opt-in process for proposing features in order to get better, more-upfront signals about how features are progressing. The WHATWG Steering Group has discussed this already, and we'd like to invite the broader community to weigh in.

What problems are we trying to solve?

The WHATWG has historically operated in a very lightweight, minimal-process fashion. This works very well in some cases, especially when implementers and editors are all engaged. However, we've found that it can be problematic for newcomers, who don't know how to reliably get implementer feedback or editor time commitment. This can discourage contributions, and it can lead to frustration when implementer/editor feedback arrives late in the process after the contributor feels "close to done".

The WHATWG's "document reality" approach has been effective for nailing down HTML, DOM, XHR, and similar fundamental parts of the platform and improving interoperability and developer satisfaction. Additionally, when enthusiastic editors have been involved, new APIs for developers have been effectively incubated within WHATWG, with speculative text included in living standards even before multiple implementations were created. (For example: Fetch, Storage, Encoding, and URL.) But there is not a clear on-ramp for incubation efforts for contributors who aren't already editors, especially for additions to existing specs.

The stage process proposed here is an optional, opt-in process that a feature proposer can use if they want to get more formal signals about how their feature is progressing. It asks for explicit implementer involvement at multiple stages, 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. This can be more helpful than the current practice of using a single boolean checkbox for implementer interest, which implementers usually are unwilling to hand out until the very end. Like with the current practice, if not enough implementers agree to work on a problem, the proposer can keep incubating their idea outside of the WHATWG, including by shipping it speculatively in a browser.

As a bonus, these sorts of explicit signals are also useful to the broader community, not just to the contributor. Notice how JavaScript developers are very keenly aware of what is making its way through TC39. They do this by monitoring the proposals that are moving through the various stages, tweeting about stage advancements, giving talks about upcoming stage 2 proposals, etc. By explicitly signaling a proposal's progress, including implementer involvement, the community will have a better idea of what is going on in WHATWG-land.

We anticipate this mostly being used for medium-to-large new features. Examples of this sort of thing that have already landed, but would have benefited had we had the process, include: popover, <dialog> focus changes, the imperative slot API, and cross-origin opener policies. Examples of upcoming features that might want to adopt this process (or might not) include: HDR canvas colors, <selectmenu>, CompressionStream, and URLPattern.

Details

This document proposes a set of formal checkpoints for new features in existing WHATWG specs, and that the WHATWG may host some draft specifications (e.g. in a branch). 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, and/or intent to implement and ship the feature in browser engines, and signals progress to web developers.

Out of scope: process for adding a feature that does not fit in any existing WHATWG spec.

Terminology:

• Stage: each successive stage is closer to a landed spec and interoperable implementation.
• Browser engine: an independent implementation of the web platform (e.g. Chromium, WebKit and Gecko at present).
• Implementation interest: a direct signal from a browser engine that a feature is on the roadmap to implement [Ed: same as in current process].
• Browser engine representatives: persons delegated by a browser engine to indicate implementation interest.
• Proposal champion: person/organization that proposed and will advance a feature through the stages, typically including writing the specification, researching use cases, and prototyping.

Process:

• Any proposal starts at Stage 0 without any approvals, by a proposal champion filing a new issue on a relevant WHATWG spec.
• It is expected that the champion of a proposal will support R&D as time allows, through answering questions asynchronously, providing feedback when requested, and consideration of important open questions at triage meetings.
• Stage level will be tracked with labels on issues in the relevant specifications—we will add “stage 0”, “stage 1”, etc labels.
• Stage labels (other than stage 0) should only be added by browser engine representatives, or by Editors on the relevant specification, after showing the necessary support for a level.
• Advancing stages
  • The feature champion should bring the proposal to the WHATWG to advance to the next stage by setting a “stage review needed” label on the tracking issue. Advancing 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 feature 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 proposal 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 proposals 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.

Stage Name	Entrance criteria	This stage signifies	Spec quality at entrance
Stage 0 (Proposal)	(None)	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 user/developer problem to be solved, including sketching use cases and scenarios. This explainer can exist anywhere, including e.g. a GitHub issue, or a personal repository.
Stage 1 (Incubation)	A comprehensive explainer for the feature, 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 feature's champion. \ \ Identification of a relevant WHATWG Workstream and Standard that will host the feature, 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 spec community to do work on the specification, which includes: review the spec and discussion about API improvements and adjustments. \ \ The WHATWG commits to hosting a specification draft in a repository or branch (if the champion requests it).	The explainer follows the guidelines at https://tag.w3.org/explainers/.
Stage 2 (Iteration)	A draft specification for the feature, 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 feature to be developed and eventually included in the relevant WHATWG standard. This stage also demonstrates commitment from the spec community to review the specification, and commitment from the champion 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 (Committed)	Complete spec text. Support of at least two implementers to land the feature 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 spec 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 PR to add the feature, with an expectation of landing soon.	Spec is complete: all semantics, syntax 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 (Standard)	Editor’s comments on PR have all been resolved, and the PR for the feature has been merged by the Editor.	The PR has been approved to change a WHATWG Living Standard.	The feature is merged into the WHATWG Living Standard.

[othermaciej]

Meta: should this perhaps be filed at https://github.com/whatwg/sg instead, since it is proposing a new policy / changes to a policy?

[cwilso]

This was discussed in SG already, and is being tracked there: whatwg/sg#212. We agreed I should file the proposal here to get more attention on it.

After discussing in TPAC 2023, there was clear support for us to trial this idea, so the SG will figure out implementation. I do want to underscore that it's additive - a way to get more eyes on and build support for a proposal - it's not rewriting policy. It will be opt-in.

[foolip]

To get something rolling, I think we can add these labels to https://github.com/whatwg/html for a trial run:

Label	Description
stage: 0	Proposal
stage: 1	Incubation
stage: 2	Iteration
stage: 3	Committed
stage: 4	Standard

(Matching the format of the topic: foo labels.)

We'll need an additional label that apply to any tracked proposal, since it's not possible to search for issues with one of multiple labels. I suggest that we use the existing addition/proposal label, but that we don't try to backfill stage: 0 for all of them until we're confident that the labels approach is the right one. Then we'd also need a migration plan for the widely used needs implementer interest label.

@annevk WDYT about those 5 labels as an implementation of this?

[domenic]

it's not possible to search for issues with one of multiple labels

It is possible :)

[cwilso]

LGTM; I definitely agree we shouldn't backfill stage:0.

[foolip]

@domenic Thanks, TIL :)

[foolip]

The 5 labels have now been created on whatwg/html.