Re: [w3ctag/design-reviews] Rethink the TAG's review intake process. (PR #1102) from Jeffrey Yasskin on 2025-06-10 (public-webapps-github@w3.org from June 2025)

From: Jeffrey Yasskin <notifications@github.com>
Date: Mon, 09 Jun 2025 17:57:20 -0700
To: w3ctag/design-reviews <design-reviews@noreply.github.com>
Cc: Subscribed <subscribed@noreply.github.com>
Message-ID: <w3ctag/design-reviews/pull/1102/review/2911266331@github.com>
@jyasskin commented on this pull request.



> +
+  - type: input
+    attributes:
+      label: Specification
+      placeholder: Enter a URL.
+      value: "https://"
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Other documents
+      description: List any other documents that are relevant to our review.
+      value: |
+        - A description of what has changed since our previous review: <!-- URL -->
+        - Explainer(s) for specifically the changed features: <!-- Based on https://w3ctag.github.io/explainer-explainer/. If sections of that have moved to the specification, link directly to those sections or risk getting feedback on the whole spec. -->

I've replaced this with requests to link to sections (or issues) describing the individual features, so it doesn't imply that you need separate explainer documents for each. But I think we want, for example, a description of the alternatives considered for each change, so we that we don't have to invent those alternatives and then ask you about them.

> +      label: The specification and other documents
+      options:
+        - label: Include an introduction that's understandable by people who weren't familiar with the problem space.
+          required: true
+        - label: Describe [the problems that end-users were facing](https://w3ctag.github.io/explainer-explainer/#end-user-need) before this proposal.
+          required: true
+        - label: Describe the [alternatives that you considered](https://w3ctag.github.io/explainer-explainer/#alternatives).
+          required: true
+        - label: Give [examples of how to use the proposal to solve the end-users' problems, and what the end-users wind up experiencing](https://w3ctag.github.io/explainer-explainer/#describe-proposal).
+        - label: Describe user research you did to validate the problem and/or design.
+        - label: Follow the [Web Platform Design Principles](https://www.w3.org/TR/design-principles/).
+        - label: Include Security and Privacy Considerations sections based on answers to the [Security/Privacy Questionnaire](https://www.w3.org/TR/security-privacy-questionnaire/).

I can do that _instead_ of checkboxes, by putting this into one of the textarea sections. Let's see how this new version looks...

> +        - label: Describe user research you did to validate the problem and/or design.
+        - label: Follow the [Web Platform Design Principles](https://www.w3.org/TR/design-principles/).
+        - label: Include Security and Privacy Considerations sections based on answers to the [Security/Privacy Questionnaire](https://www.w3.org/TR/security-privacy-questionnaire/).
+<% } -%>
+
+<% if (type.startsWith("wg-")) { -%>
+  - type: textarea
+    attributes:
+      label: Concurrent horizontal reviews
+      description: Link to where the [other horizontal review groups](https://www.w3.org/guide/documentreview/#how-to-get-horizontal-review) have been asked for feedback.
+      value: |
+        - Accessibility: https://github.com/w3c/a11y-request/issues/###
+        - Internationalization: https://github.com/w3c/i18n-request/issues/###
+        - Privacy: https://github.com/w3cping/privacy-request/issues/###
+        - Security: https://github.com/w3c/security-request/issues/###
+        <!-- Or if you have a single issue that links to all of your wide review issues, like https://github.com/webmachinelearning/webnn/issues/239, you can just link to that here. -->

Done.

> @@ -0,0 +1,73 @@
+name: Early design/incubation review
+description: >
+  If you'd like the TAG to offer thoughts and guidance
+  on an early-stage design direction.
+title: "Incubation: "
+labels:
+  - "Progress: untriaged"
+  - "Review type: CG early review"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for sending us your design review.

Done.

> +
+        Use links to content rather than pasting text into this issue. Issues are ephemeral and most of the material we are asking for has long term value.
+
+        Please preview the issue and check that the links work before submitting. Please make sure anyone with the link can access the document. We may refuse to review anything that is not public.
+

Done, except that the "Issues are ephemeral" sentence explains the "Use links" action item, so I left it in the first bullet point.

> +  - "Progress: untriaged"
+  - "Review type: CG early review"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for sending us your design review.
+
+        Use links to content rather than pasting text into this issue. Issues are ephemeral and most of the material we are asking for has long term value.
+
+        Please preview the issue and check that the links work before submitting. Please make sure anyone with the link can access the document. We may refuse to review anything that is not public.
+
+  - type: input
+    attributes:
+      label: Explainer
+      description: An explainer must address user needs and contain examples of use. See our [explanation of how to write a good explainer](https://w3ctag.github.io/explainer-explainer/#introduction).

This text was directly from the old template: https://github.com/w3ctag/design-reviews/blob/d44e371b196a9c07dde27d149dc8f9885462d2eb/.github/ISSUE_TEMPLATE/005-early-design-review.md?plain=1#L51

But I don't mind improving it here. I took some more words from https://w3ctag.github.io/explainer-explainer/#introduction on the theory that the UI for this form makes it easier to focus on the relevant paragraphs than the footnote-based textbox it's replacing.

Showing ["example pieces of code"](https://w3ctag.github.io/explainer-explainer/#introduction:~:text=example%20pieces%20of%20code) does risk that the proponents get stuck on a particular solution, but in my experience nobody does a good job of reviewing a proposal that's just a problem statement. If only to invoke [Cunningham's Law](https://meta.wikimedia.org/wiki/Cunningham%27s_Law), we need at least one solution sketched out in order to start thinking about whether it's the right one.

> +        For your own organization, you can simply state the organization's position instead of linking to it.  This includes items on [Mozilla standards-positions](https://github.com/mozilla/standards-positions), and [WebKit standards-positions](https://github.com/WebKit/standards-positions).  Chromium doesn't have a standards-positions repository and [prefers](https://source.chromium.org/chromium/chromium/src/+/main:docs/standards/positions/GoogleChrome/README.md) to use comments from the teams that maintain the relevant area of their codebase.
+      value: |
+        - Multi-stakeholder feedback:
+          - Chromium comments:
+          - Mozilla comments: https://github.com/mozilla/standards-positions/issues/NNN <!-- And/or other places they've given feedback -->
+          - WebKit comments: https://github.com/WebKit/standards-positions/issues/NNN <!-- And/or other places they've given feedback -->
+          - {{...include feedback/review from developers, implementers, civil society, and others}}
+        - Major unresolved issues with or opposition to this design:
+
+  - type: textarea
+    attributes:
+      label: You should also know that...
+      description: |
+        Please tell us anything else you think is relevant to this review.
+
+        If you have any other documents that you want us to read, link them here, especially if they're not obvious from the explainer. If you've started a specification, link it here too.

No, that comma was important.

> +        - GitHub repo:
+        - Primary contacts:
+          - $name (@-mention), $organization/s, $role in developing specification
+          - <!-- repeat as necessary, we recommend including group chairs and editors in this list -->
+        - Organization/project driving the specification:
+        - This work is being funded by:
+        - Primary standards group developing this feature:
+        - Incubation and standards groups that have discussed the design:
+          - {{ABC CG}} <!-- Include a link to minutes or issues in this group if possible. -->
+          - {{DEF WG}}
+
+  - type: textarea
+    attributes:
+      label: Feedback so far
+      description: |
+        For your own organization, you can simply state the organization's position instead of linking to it.  This includes items on [Mozilla standards-positions](https://github.com/mozilla/standards-positions), and [WebKit standards-positions](https://github.com/WebKit/standards-positions).  Chromium doesn't have a standards-positions repository and [prefers](https://source.chromium.org/chromium/chromium/src/+/main:docs/standards/positions/GoogleChrome/README.md) to use comments from the teams that maintain the relevant area of their codebase.

Switching sentence boundaries from double-space to single-space doesn't seem worth it, especially if we only catch half of the sentences.

> +          - {{ABC CG}} <!-- Include a link to minutes or issues in this group if possible. -->
+          - {{DEF WG}}
+
+  - type: textarea
+    attributes:
+      label: Feedback so far
+      description: |
+        For your own organization, you can simply state the organization's position instead of linking to it.  This includes items on [Mozilla standards-positions](https://github.com/mozilla/standards-positions), and [WebKit standards-positions](https://github.com/WebKit/standards-positions).  Chromium doesn't have a standards-positions repository and [prefers](https://source.chromium.org/chromium/chromium/src/+/main:docs/standards/positions/GoogleChrome/README.md) to use comments from the teams that maintain the relevant area of their codebase.
+      value: |
+        - Multi-stakeholder feedback:
+          - Chromium comments:
+          - Mozilla comments: https://github.com/mozilla/standards-positions/issues/NNN <!-- And/or other places they've given feedback -->
+          - WebKit comments: https://github.com/WebKit/standards-positions/issues/NNN <!-- And/or other places they've given feedback -->
+          - {{...include feedback/review from developers, implementers, civil society, and others}}
+        - Major unresolved issues with or opposition to this specification:
+        - Status/issue trackers for implementations⁴: <!-- Include links to [Chrome Status](https://chromestatus.com/), [Mozilla's](https://bugzilla.mozilla.org/), [WebKit's Bugzilla](https://bugs.webkit.org/), and trackers for other implementations if those are known to you. -->

Nope, it was left over from the old templates. Thanks!

> @@ -0,0 +1,89 @@
+name: Browser-driven specification review
+description: >
+  If your browser is considering shipping a feature
+  that hasn't had a Working Group take it through wide review,
+  please use this form.
+title: "Browser review: "
+labels:
+  - "Progress: untriaged"
+  - "Review type: later review"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for sending us your specification review. If a Working Group generally agrees about this feature, we prefer to have them take it through wide review. If they're willing to do that, please [switch to the WG new specification review template](https://github.com/w3ctag/design-reviews/issues/new?template=005-wg-new-spec-review.yaml). Otherwise, if you're planning to ship the feature anyway, please continue to file the review with this form.

I'll add a note that this review process is only for features in a Community Group or similar incubation process, or later. But there's still a lot of space between entering a CG and having a WG ready to advance a feature to CR.

-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/pull/1102#discussion_r2136716918
You are receiving this because you are subscribed to this thread.

Message ID: <w3ctag/design-reviews/pull/1102/review/2911266331@github.com>
Received on Tuesday, 10 June 2025 00:57:24 UTC