Rethink the TAG's review intake process. #1102
Conversation
| 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. --> |
There was a problem hiding this comment.
This feels a bit heavyweight -- can we replace this with a list of issues/PRs that have been processed along with the class of change they make to the spec. We could also include a summary of what has changed. The reasoning here is that revisions to specifications are often in response to issues raised and those issues typically contain the details of why the change was made. I get that it would be nice for the TAG and other groups to have a summary of changes, and so maybe a paragraph or four would be fine in that case... but having to write an entire explainer to just cover a handful of issues in a maintenance release seems a bit much.
There was a problem hiding this comment.
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/). |
There was a problem hiding this comment.
I don't know if it's possible to enable links to be provided for these checkboxes? It seems like at this point in the process that you should be able to point to specific sections in the spec that cover these points.
There was a problem hiding this comment.
I can do that instead of checkboxes, by putting this into one of the textarea sections. Let's see how this new version looks...
.github/ISSUE_TEMPLATE/gen.sh
Outdated
| $NPX ejs intake.yaml.ejs -i '{"type": "incubation"}' -o 000-incubation-review.yaml | ||
| $NPX ejs intake.yaml.ejs -i '{"type": "wg-new"}' -o 005-wg-new-spec-review.yaml | ||
| $NPX ejs intake.yaml.ejs -i '{"type": "wg-revision"}' -o 010-wg-revision-review.yaml | ||
| $NPX ejs intake.yaml.ejs -i '{"type": "browser"}' -o 015-browser-review.yaml |
There was a problem hiding this comment.
This is excellent, I really like these categories.
| - 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. --> |
There was a problem hiding this comment.
I'd rather we just request ONE issue that is tracking all horizontal reviews for the spec. Otherwise, it requires all other horizontal reviews to be opened before TAG review happens... and some of those other horizontal reviews require Explainers (which I hope this whole intake process changes).
The WGs have to track all horizontal reviews anyway, so why not just standardize on a single issue that's tracking all horizontal reviews?
|
@jyasskin wrote:
This is excellent, @jyasskin -- thank you! It certainly addresses the greatest pain points that our WGs have experienced based on the current TAG intake process. I haven't used every checkbox on every form yet, but this (currently in draft form) is going in a really good direction. |
| - type: markdown | ||
| attributes: | ||
| value: | | ||
| Thank you for sending us your design review. |
There was a problem hiding this comment.
| Thank you for sending us your design review. | |
| Thank you for sending us your design for 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. | ||
|
|
There was a problem hiding this comment.
| 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. | |
| * 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). | |
There was a problem hiding this comment.
Done, except that the "Issues are ephemeral" sentence explains the "Use links" action item, so I left it in the first bullet point.
| - 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). |
There was a problem hiding this comment.
My only concern with the examples of usage is that it's asking for a solution to be "engineered". That risks locking in some kind of design (e.g., JS vs markup or whatever) - where there might be multiple ways to solve a problem.
| 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). | |
| description: An explainer must explain the value to end users and contain examples of use, even if hypothetical. See our [explanation of how to write a good explainer](https://w3ctag.github.io/explainer-explainer/#introduction). |
There was a problem hiding this comment.
This text was directly from the old template:
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" 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, we need at least one solution sketched out in order to start thinking about whether it's the right one.
| 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. |
There was a problem hiding this comment.
Fixed whitespace
| 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. | |
| 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. |
| 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. |
There was a problem hiding this comment.
| 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. | |
| 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. |
There was a problem hiding this comment.
No, that comma was important.
| 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. |
There was a problem hiding this comment.
tiny whitespace fix
| 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. | |
| 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. |
There was a problem hiding this comment.
Switching sentence boundaries from double-space to single-space doesn't seem worth it, especially if we only catch half of the sentences.
| - 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. --> |
There was a problem hiding this comment.
Is that "⁴" intentional?
There was a problem hiding this comment.
Nope, it was left over from the old templates. Thanks!
| - 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. |
There was a problem hiding this comment.
This still reads like, "hey TAG, review our proprietary feature".
I don't think the TAG should spend time reviewing things that haven't initiated a standardization process (even if it's an incubation process).
There was a problem hiding this comment.
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.
|
Is a preview and/or diff of this set of changes available? |
|
@nigelmegitt Yes, I've staged the forms into https://github.com/jyasskin/test-design-reviews/issues/new/choose, and anyone should feel free to file test issues there to find problems with how the forms work, or what their output looks like. |
Thanks, very helpful, looks good to me on a quick scan; usage experience may lead to requests for tweaks, of course. |
|
Overall, there are some improvements here. The mix of forms and text boxes with form-like fields is a bit strange. Are you concerned about the format of the markdown that results from using all-forms, is this a partial migration, or something else? |
|
@martinthomson I tried an all-form migration before, and you can see the result in jyasskin/test-design-reviews#7. I think all the headings wind up taking too much vertical space, although if other folks prefer that, I'm not completely opposed. |
This arranges review intake into 4 tracks:
This makes progress on w3ctag/explainer-explainer#19, but that issue also needs a resolution to w3ctag/explainer-explainer#6 before it'll be really fixed.
I've staged the forms into https://github.com/jyasskin/test-design-reviews/issues/new/choose, and anyone should feel free to file test issues there to find problems with how the forms work, or what their output looks like.