From 6b2811cc1ddc248aaeba83b52a7cf467c8b96d5f Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Tue, 6 Feb 2024 10:04:12 -0500 Subject: [PATCH] Add Stages.md, revise Working Mode to include (#222) * Add Stages.md, revise Working Mode to include * Update Working Mode.md Co-authored-by: Anne van Kesteren * Revise to read like a policy as per @annevk's feedback * Round 2 of rewriting as policy * Update Stages.md Co-authored-by: Jeremy Roman * Update Stages.md * bullet fixes * bullet fixes * Update bullets. * remove "current process" mention * fundamental parts of the platform Co-authored-by: Domenic Denicola * parabreak, WHATWG-land -> the WHATWG Co-authored-by: Domenic Denicola * specs->LS, tweaks Co-authored-by: Domenic Denicola * Gh -> GH Co-authored-by: Domenic Denicola * Terminology= Co-authored-by: Domenic Denicola * process= Co-authored-by: Domenic Denicola * Address feedback Remove subtitle, add s, THEAD structure --------- Co-authored-by: Anne van Kesteren Co-authored-by: Jeremy Roman Co-authored-by: Domenic Denicola --- Stages.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++ Working Mode.md | 2 +- 2 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 Stages.md diff --git a/Stages.md b/Stages.md new file mode 100644 index 0000000..81089e1 --- /dev/null +++ b/Stages.md @@ -0,0 +1,131 @@ +# Stages + +The WHATWG's "document reality" approach has been effective for nailing down [fundamental parts of the platform](https://spec.whatwg.org/) and improving interoperability and developer satisfaction. However, our process can sometimes be daunting 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 stage process described here is an additional tool designed to help provide a clear on-ramp for incubation efforts for contributors who aren't already editors, especially for additions to existing specs. Stages are 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. + +Stage signals are also useful to the broader community, helping developers monitor the proposals that are moving through the various stages. By explicitly signaling a proposal's progress, including implementer involvement, the community has a better idea of what is going on in the WHATWG. + +This tool is generally used for medium-to-large new features; it's not expected that explicit stage progression will be used for every feature. + +# Details + +This document formalizes some signal checkpoints for new features in existing WHATWG Living Standards. These checkpoints are modeled loosely on the [TC39 process](https://tc39.es/process-document/), which uses the concept of _stages_. Each subsequent stage implies a larger degree of consensus from the community, willingness to engage and/or implement and ship the feature in browser engines, and signals progress to web developers. These checkpoints are not required for all features; this is simply a way to ensure that attention is appropriately drawn to incubations that have grown community support behind them. + +## Terminology + +* Stage: each successive stage is closer to a landed spec and interoperable implementation. These stages are tracked on the issues in the relevant WHATWG GitHub repository, using labels ("stage 0", "stage 1", etc.) +* 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, as defined in [working mode](https://whatwg.org/working-mode#additions)]. +* 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 effectively starts at Stage 0 without any approvals, by a community member filing a new issue on a relevant WHATWG spec. +* In order to drive a proposal forward, it is expected that a community member will step up to champion the proposal, through answering questions asynchronously, providing feedback when requested, and consideration of important open questions at triage meetings. +* Stage level is tracked with labels on issues in the relevant specifications — “stage 0”, “stage 1”, etc. +* 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 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](https://whatwg.org/working-mode#additions)). 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).
+ 		+
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.
+
\ No newline at end of file diff --git a/Working Mode.md b/Working Mode.md index 03e2bc4..8460c5b 100644 --- a/Working Mode.md +++ b/Working Mode.md @@ -109,7 +109,7 @@ In such scenarios we anticipate features will be “incubated” outside of WHAT In all cases, features that hope to graduate to a WHATWG standard should strive to follow the above guidelines, gather appropriate implementer commitments, and have corresponding tests. -Additionally, those maintaining such proposals should try to involve the WHATWG community, for example by filing an issue on the standard they anticipate eventually becoming a part of. +Additionally, those maintaining such proposals should try to involve the WHATWG community, for example by filing an issue on the standard they anticipate eventually becoming a part of. We also have the optional [Stages](Stages.md) process to help gather attention on proposals as they progress. NOTE: Overall, this process of incubation can be very lightweight, such as filing a pull request on the appropriate WHATWG standard with a proposal, and gathering appropriate implementer support there. Or it could be more involved, such as creating a separate repository at another venue and iterating for a long time there.