Fill in template contents for explainer repositories. #1

jyasskin · 2023-11-23T00:55:28Z

@tabatkins, let me know what changes you suggest for the initial Bikeshed file.

cwilso

Two requested changes:

The instructions say "look for TODO" but really, each section needs to be filled out - either a bunch of sections need TODO in them, or just say "fill all this out".
Maybe I'm misunderstanding the Key Scenarios sections (or it needs retitling to "API interactions" or something), but it seems like it needs to come further up, where use cases and scenarios are listed.

cwilso · 2023-11-28T18:20:16Z

README.md

+
+## Proponents
+
+- [Proponent team 1]


Should these have "todo" on them, or should the instructions say to look for brackets?

I hope moving the "TODO: Fill in the whole explainer template" bit above this is sufficient.

cwilso · 2023-11-28T18:20:35Z

README.md

+- [etc.]
+
+## Participate
+- [Issue tracker]


As above: todo here?

cwilso · 2023-11-28T18:21:31Z

README.md

+
+## Introduction
+
+TODO: Fill this in using https://tag.w3.org/explainers/ as a reference.


It's not clear if this TODO is for the entire following sections or not?

I've moved it up to the top of the explainer and reworded a bit so it's clear it covers the whole thing.

cwilso · 2023-11-28T18:22:56Z

README.md

+
+[If spec work is in progress, link to the PR or draft of the spec.]
+
+## [Potential Solution 2]


This is possible, but relatively unlikely (that a second+ solution would be documented, right? Perhaps we should remove this, but above say "there may be more than one potential solution section".

Sounds good.

cwilso · 2023-11-28T18:24:53Z

README.md

+<!-- In your initial explainer, you shouldn't be attached or appear attached to any of the potential
+solutions you describe below this. -->
+
+## [Potential Solution 1]


The potential solution(s) should be below the "tricky design choice" section below, but DEFINITELY after the Key Scenarios.

cwilso · 2023-11-28T18:25:53Z

README.md

+and a brief overview of how the solution works.
+This should be no more than 1-2 paragraphs.]
+
+## Goals [or Motivating Use Cases, or Scenarios]


Not clear how this interacts with the Key Scenarios below? Definitely need to make sure htis gets filled out, in depth, prior to the potential solution.

Yeah. I took this directly from the TAG's template, but it's not clear. I think the idea was to list use cases here, and then have the Key Scenarios explain how the potential solutions solve the use cases. I'll try to make that clearer ... and then also send the TAG a patch.

tabatkins · 2023-11-28T18:23:20Z

index.bs

+
+For now, see the [explainer]([REPOSITORYURL]).
+
+See [https://speced.github.io/bikeshed/](https://speced.github.io/bikeshed/) to get started on your specificaton.


Drop in links to the other "how to Bikeshed" and "how to spec" links? So people have several jumping off points, besides just the (sometimes intimidating) Bikeshed docs.

tabatkins · 2023-11-28T19:09:06Z

index.bs

+Repository: explainers-by-googlers/todo-your-repo-name
+URL: https://explainers-by-googlers.github.io/todo-your-repo-name
+Editor: TODO: Your Name, Google https://google.com, [email protected]
+!Tests: <a href=https://github.com/w3c/web-platform-tests/tree/master/todo-api-label>web-platform-tests todo-api-label/</a> (<a href=https://github.com/w3c/web-platform-tests/labels/todo-api-label>ongoing work</a>)


Is there a particular reason you're suggesting an explicitly-constructed WPT line, rather than using the Bikeshed's WPT features directly? This method won't, for example, fill in any test results.

Suggest instead a WPT Path Prefix: TODO-API-LABEL and WPT Display: closed, along with a <wpt rest></wpt> at the end of the body along with a short note explaining how to properly sprinkle <wpt> thruout the document.

This is what npx wicg produced: https://github.com/WICG/starter-kit/blob/main/templates/index.bs. I've taken your suggestion, and I'll update that once this template is merged.

jyasskin

Thanks for the reviews. How's this?

jyasskin · 2023-11-28T19:16:18Z

index.bs

+Repository: explainers-by-googlers/todo-your-repo-name
+URL: https://explainers-by-googlers.github.io/todo-your-repo-name
+Editor: TODO: Your Name, Google https://google.com, [email protected]
+!Tests: <a href=https://github.com/w3c/web-platform-tests/tree/master/todo-api-label>web-platform-tests todo-api-label/</a> (<a href=https://github.com/w3c/web-platform-tests/labels/todo-api-label>ongoing work</a>)


This is what npx wicg produced: https://github.com/WICG/starter-kit/blob/main/templates/index.bs. I've taken your suggestion, and I'll update that once this template is merged.

jyasskin · 2023-11-28T19:16:23Z

index.bs

+
+For now, see the [explainer]([REPOSITORYURL]).
+
+See [https://speced.github.io/bikeshed/](https://speced.github.io/bikeshed/) to get started on your specificaton.


jyasskin · 2023-11-28T19:23:56Z

README.md

+
+[If spec work is in progress, link to the PR or draft of the spec.]
+
+## [Potential Solution 2]


Sounds good.

jyasskin · 2023-11-28T19:26:26Z

README.md

+
+## Introduction
+
+TODO: Fill this in using https://tag.w3.org/explainers/ as a reference.


I've moved it up to the top of the explainer and reworded a bit so it's clear it covers the whole thing.

jyasskin · 2023-11-28T19:26:57Z

README.md

+
+## Proponents
+
+- [Proponent team 1]


I hope moving the "TODO: Fill in the whole explainer template" bit above this is sufficient.

jyasskin · 2023-11-28T19:38:55Z

README.md

+and a brief overview of how the solution works.
+This should be no more than 1-2 paragraphs.]
+
+## Goals [or Motivating Use Cases, or Scenarios]


Yeah. I took this directly from the TAG's template, but it's not clear. I think the idea was to list use cases here, and then have the Key Scenarios explain how the potential solutions solve the use cases. I'll try to make that clearer ... and then also send the TAG a patch.

jyasskin · 2023-11-28T20:05:07Z

index.bs

+and [https://speced.github.io/bikeshed/](https://speced.github.io/bikeshed/) to get started on your
+specificaton.
+
+<wpt rest></wpt>


Hmmm, @tabatkins this spelling produces an "Attribute “rest” not allowed on element “details” at this point." error in spec-prod's markup validation. Using <wpt-rest> as suggested in https://speced.github.io/bikeshed/#elementdef-wpt-rest fails Bikeshed with

FATAL ERROR: Couldn't find any tests with the path prefix 'TODO-API-LABEL'.

I could just remove this or comment this out, since the issue tells people what to do once they set their WPT Path Prefix. What do you think?

Sorry, yes, <wpt-rest> is what I meant.

Re: the fatal error; go ahead and just ignore my suggestion for a wpt-rest, actually. It works just fine as-is; it (currently) won't complain at all about a nonsense path prefix as long as you don't actually use any wpt-related elements. But when that TODO is replaced with the actual path prefix, it'll start complaining about tests not being specified, which is good. (Tho I really need to work on the error message...)

Removed. :)

When the spec author fills in the WPT Path Prefix, it'll give them errors that say to add <wpt> elements, which is as good as an inline issue.

SHA: 2e383d8 Reason: push, by jyasskin Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Fill in template contents for explainer repositories.

743fece

jyasskin requested a review from cwilso November 23, 2023 00:55

jyasskin added 3 commits November 22, 2023 16:57

Fix an invalid markup error.

8bcd746

Remove more angle brackets...

8e7f440

Add the required intro text.

3d984a5

cwilso requested changes Nov 28, 2023

View reviewed changes

tabatkins reviewed Nov 28, 2023

View reviewed changes

jyasskin added 2 commits November 28, 2023 11:58

Take Tab's suggestions.

76373e7

Try to fix Chris's comments.

c36d74f

jyasskin commented Nov 28, 2023

View reviewed changes

cwilso approved these changes Nov 28, 2023

View reviewed changes

Remove the <wpt> bits in the content.

8273087

When the spec author fills in the WPT Path Prefix, it'll give them errors that say to add <wpt> elements, which is as good as an inline issue.

jyasskin merged commit 2e383d8 into main Nov 28, 2023
2 checks passed

jyasskin deleted the initial-template branch November 28, 2023 21:29

github-actions bot added a commit that referenced this pull request Nov 28, 2023

Fill in template contents for explainer repositories. (#1)

5efb44e

SHA: 2e383d8 Reason: push, by jyasskin Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fill in template contents for explainer repositories. #1

Fill in template contents for explainer repositories. #1

jyasskin commented Nov 23, 2023 •

edited

Loading

cwilso left a comment

cwilso Nov 28, 2023

jyasskin Nov 28, 2023

cwilso Nov 28, 2023

cwilso Nov 28, 2023

jyasskin Nov 28, 2023

cwilso Nov 28, 2023

jyasskin Nov 28, 2023

cwilso Nov 28, 2023

cwilso Nov 28, 2023

jyasskin Nov 28, 2023

tabatkins Nov 28, 2023

jyasskin Nov 28, 2023

tabatkins Nov 28, 2023

jyasskin Nov 28, 2023

jyasskin left a comment

jyasskin Nov 28, 2023

jyasskin Nov 28, 2023

jyasskin Nov 28, 2023

jyasskin Nov 28, 2023

jyasskin Nov 28, 2023

jyasskin Nov 28, 2023

jyasskin Nov 28, 2023

tabatkins Nov 28, 2023

jyasskin Nov 28, 2023


		## Introduction

		TODO: Fill this in using https://tag.w3.org/explainers/ as a reference.


		[If spec work is in progress, link to the PR or draft of the spec.]

		## [Potential Solution 2]


		For now, see the [explainer]([REPOSITORYURL]).

		See [https://speced.github.io/bikeshed/](https://speced.github.io/bikeshed/) to get started on your specificaton.

Fill in template contents for explainer repositories. #1

Fill in template contents for explainer repositories. #1

Conversation

jyasskin commented Nov 23, 2023 • edited Loading

cwilso left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyasskin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyasskin commented Nov 23, 2023 •

edited

Loading