From abad09564fc683a2f09b2fafba074ba8749bbd89 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Tue, 16 Jan 2024 17:20:26 -0800 Subject: [PATCH 01/17] Add Stages.md, revise Working Mode to include --- Stages.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++ Working Mode.md | 2 +- 2 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 Stages.md diff --git a/Stages.md b/Stages.md new file mode 100644 index 0000000..8b075bc --- /dev/null +++ b/Stages.md @@ -0,0 +1,147 @@ +# Stages - tool for encouraging attention to incubation features + +## 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 also that the WHATWG may host some draft specifications (e.g. in a branch). 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 intent to 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. + +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. 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 [Ed: same as in [current process](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 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 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 stagerequires 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). +

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. +
\ No newline at end of file diff --git a/Working Mode.md b/Working Mode.md index fe50b85..580bab6 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 incubations as they mature. 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. From e1aa0d615348fbb193436790b6b5ab83cb0f665f Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 12:58:05 -0800 Subject: [PATCH 02/17] Update Working Mode.md Co-authored-by: Anne van Kesteren --- Working Mode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Working Mode.md b/Working Mode.md index 580bab6..378f5b0 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. We also have the optional [Stages](Stages.md) process to help gather attention on incubations as they mature. +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. From 7e272705ed3d54a3c30c33d074194daff1f9e1fe Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 13:25:27 -0800 Subject: [PATCH 03/17] Revise to read like a policy as per @annevk's feedback --- Stages.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/Stages.md b/Stages.md index 8b075bc..6672916 100644 --- a/Stages.md +++ b/Stages.md @@ -6,18 +6,15 @@ The WHATWG has historically operated in a very lightweight, minimal-process fash 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. +The stage process described 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 previous 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. +These sorts of explicit signals are also useful to the broader community, not just to the contributor. 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. +This is generally used for medium-to-large new features; it's not expected that it will be used for every feature. # Details -This document proposes a set of formal checkpoints for new features in existing WHATWG specs, and also that the WHATWG may host some draft specifications (e.g. in a branch). 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 intent to 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. - -Out of scope: process for adding a feature that does not fit in any existing WHATWG spec. +This document formalizes some signal checkpoints for new features in existing WHATWG specs. 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 intent to 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: @@ -29,9 +26,9 @@ Terminology: 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. +* 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 stagerequires 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. From be8b43b8958220a49ab6bb8c186adb1690c94b3b Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 13:32:09 -0800 Subject: [PATCH 04/17] Round 2 of rewriting as policy --- Stages.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/Stages.md b/Stages.md index 6672916..14f4c31 100644 --- a/Stages.md +++ b/Stages.md @@ -1,16 +1,10 @@ -# Stages - tool for encouraging attention to incubation features +# Stages - a tool for encouraging attention to incubation features -## What problems are we trying to solve? +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. 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 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 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. -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 described 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 previous 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. - -These sorts of explicit signals are also useful to the broader community, not just to the contributor. 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. - -This is generally used for medium-to-large new features; it's not expected that it will be used for every feature. +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 WHATWG-land. 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 From 927b502da1ea9faa16d61f77f852d107557b2735 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 14:56:32 -0800 Subject: [PATCH 05/17] Update Stages.md Co-authored-by: Jeremy Roman --- Stages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Stages.md b/Stages.md index 14f4c31..6f282c7 100644 --- a/Stages.md +++ b/Stages.md @@ -25,7 +25,7 @@ Process: * 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 stagerequires 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. + * 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) From 25e5b182726a0112a9166bb0893ca52c6626e370 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 15:07:52 -0800 Subject: [PATCH 06/17] Update Stages.md --- Stages.md | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/Stages.md b/Stages.md index 14f4c31..ffa2d81 100644 --- a/Stages.md +++ b/Stages.md @@ -67,23 +67,18 @@ Stage Name

(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). + * 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. + * 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). +* 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/. + * The explainer follows the guidelines at https://tag.w3.org/explainers/. From 2a481d2b618f79f837b7c662470c42bffae3a6b1 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 15:10:17 -0800 Subject: [PATCH 07/17] bullet fixes --- Stages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Stages.md b/Stages.md index 564c0b3..944e92e 100644 --- a/Stages.md +++ b/Stages.md @@ -73,8 +73,8 @@ Stage Name * 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. -

+ +* 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). From 86e8a55933b1be1f6e58aa72674de78479f60bad Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 15:12:08 -0800 Subject: [PATCH 08/17] bullet fixes --- Stages.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Stages.md b/Stages.md index 944e92e..d390e86 100644 --- a/Stages.md +++ b/Stages.md @@ -74,9 +74,9 @@ Stage Name * 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). +

  • 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).
    • ul> * The explainer follows the guidelines at https://tag.w3.org/explainers/. From 6600b5df0ef893c30c1b3ee3c40273e2003c9c00 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 15:18:54 -0800 Subject: [PATCH 09/17] Update bullets. --- Stages.md | 62 ++++++++++++++++++++++++------------------------------- 1 file changed, 27 insertions(+), 35 deletions(-) diff --git a/Stages.md b/Stages.md index d390e86..a21c585 100644 --- a/Stages.md +++ b/Stages.md @@ -57,9 +57,9 @@ Stage Name (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). +
    • 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. +
    • 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.
    @@ -67,18 +67,18 @@ Stage Name

    (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). +

    • 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).
      • ul> +
      • 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/. + @@ -86,16 +86,13 @@ Stage Name

      (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. +

      • 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 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. +
      • 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.
      @@ -103,31 +100,26 @@ This stage also demonstrates commitment from the spec community to review the sp

      (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. +

      • 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. +

      • 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. +

      • 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. +
      • 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 PR has been approved to change a WHATWG Living Standard.
      - The feature is merged into the WHATWG Living Standard. +
      • The feature is merged into the WHATWG Living Standard.
      \ No newline at end of file From a3dcc0842e38ddb66c63e9db677a81126e7b89f0 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Thu, 25 Jan 2024 15:21:23 -0800 Subject: [PATCH 10/17] remove "current process" mention --- Stages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Stages.md b/Stages.md index a21c585..7616793 100644 --- a/Stages.md +++ b/Stages.md @@ -14,7 +14,7 @@ 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 [Ed: same as in [current process](https://whatwg.org/working-mode#additions)]. +* _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. From 7e5233e933ef22f2e6ae29013d640f262ea9e72f Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Wed, 31 Jan 2024 05:56:19 -0800 Subject: [PATCH 11/17] fundamental parts of the platform Co-authored-by: Domenic Denicola --- Stages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Stages.md b/Stages.md index 7616793..06c7af9 100644 --- a/Stages.md +++ b/Stages.md @@ -1,6 +1,6 @@ # Stages - a tool for encouraging attention to incubation features -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. 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 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. From f469c48e20db6a6186c619b2875506d8bca5d64e Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Wed, 31 Jan 2024 05:57:21 -0800 Subject: [PATCH 12/17] parabreak, WHATWG-land -> the WHATWG Co-authored-by: Domenic Denicola --- Stages.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Stages.md b/Stages.md index 06c7af9..1370759 100644 --- a/Stages.md +++ b/Stages.md @@ -4,7 +4,9 @@ The WHATWG's "document reality" approach has been effective for nailing down [fu 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 WHATWG-land. 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. +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 From e4570a633939431ac38b1aed8939df233e4b9636 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Wed, 31 Jan 2024 05:58:24 -0800 Subject: [PATCH 13/17] specs->LS, tweaks Co-authored-by: Domenic Denicola --- Stages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Stages.md b/Stages.md index 1370759..66cdb5f 100644 --- a/Stages.md +++ b/Stages.md @@ -10,7 +10,7 @@ This tool is generally used for medium-to-large new features; it's not expected # Details -This document formalizes some signal checkpoints for new features in existing WHATWG specs. 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 intent to 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. +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: From 3ce1e5cebd00f7c1f263641c338004444d27cd78 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Wed, 31 Jan 2024 05:58:51 -0800 Subject: [PATCH 14/17] Gh -> GH Co-authored-by: Domenic Denicola --- Stages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Stages.md b/Stages.md index 66cdb5f..f280dfc 100644 --- a/Stages.md +++ b/Stages.md @@ -14,7 +14,7 @@ This document formalizes some signal checkpoints for new features in existing WH 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.) +* _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. From 6ab99daebea193e959d78779a3e784702c8bd0a5 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Wed, 31 Jan 2024 06:04:54 -0800 Subject: [PATCH 15/17] Terminology= Co-authored-by: Domenic Denicola --- Stages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Stages.md b/Stages.md index f280dfc..53b38ca 100644 --- a/Stages.md +++ b/Stages.md @@ -12,7 +12,7 @@ This tool is generally used for medium-to-large new features; it's not expected 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: +## 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). From 9d888c5af54661a56700da840818f6e16b2a4569 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Wed, 31 Jan 2024 06:05:11 -0800 Subject: [PATCH 16/17] process= Co-authored-by: Domenic Denicola --- Stages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Stages.md b/Stages.md index 53b38ca..2a627ea 100644 --- a/Stages.md +++ b/Stages.md @@ -20,7 +20,7 @@ This document formalizes some signal checkpoints for new features in existing WH * _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: +## 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. From dd195992df4f01dbd374454f6642065ec8a2bbe9 Mon Sep 17 00:00:00 2001 From: Chris Wilson Date: Wed, 31 Jan 2024 09:18:31 -0500 Subject: [PATCH 17/17] Address feedback Remove subtitle, add s, THEAD structure --- Stages.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/Stages.md b/Stages.md index 2a627ea..81089e1 100644 --- a/Stages.md +++ b/Stages.md @@ -1,4 +1,4 @@ -# Stages - a tool for encouraging attention to incubation features +# 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". @@ -14,11 +14,11 @@ This document formalizes some signal checkpoints for new features in existing WH ## 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. +* 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 @@ -41,17 +41,20 @@ This document formalizes some signal checkpoints for new features in existing WH * 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 - Entrance criteria + This stage signifies + Spec quality at entrance +
      Stage 0

      @@ -124,4 +127,5 @@ Stage Name

      • The feature is merged into the WHATWG Living Standard.
      \ No newline at end of file