From 55883d5a9bbcf1f632523993a74fd6779214b726 Mon Sep 17 00:00:00 2001 From: plehegar Date: Tue, 3 Feb 2026 18:31:55 -0500 Subject: [PATCH 1/6] Upgrade the github issue template for wide review --- documentreview/create-github-issue.js | 114 +++++++++++++++++++++----- documentreview/index.md | 88 ++++++++++---------- 2 files changed, 138 insertions(+), 64 deletions(-) diff --git a/documentreview/create-github-issue.js b/documentreview/create-github-issue.js index 3318640d..59456ff1 100644 --- a/documentreview/create-github-issue.js +++ b/documentreview/create-github-issue.js @@ -1,54 +1,128 @@ -window.addEventListener('load', addGitHubIssueButton); +const repositories = fetch('https://w3c.github.io/groups/repositories.json').then(res => res.ok ? res.json() : []) + .catch(() => []); +const template = `# Wide review tracker for a specification + +This is a meta issue to track wide review steps for the specification. +See [How to do wide review](https://www.w3.org/guide/documentreview/#who-to-ask-for-wide-review) for details. + +>Legend: +>🔴 Review request not submitted +>🟡 Review request submitted +>🔵 Review feedback received +>🟢 Review closed as completed + +## Horizontal groups + +An important part of wide review is horizontal review from W3C's [key horizontal groups](https://www.w3.org/guide/documentreview/#how-to-get-horizontal-review) listed below. + +{{HORIZONTAL_GROUPS_LIST}} +## Group Dependencies + +The [charter](https://www.w3.org/groups/YOURGROUP) contains a list of dependency groups. If you skip one of those, simply provide a rational. + +🔴 ?? Group: + +- [ ] feedback requested +- [ ] feedback received +- [ ] Review closed as completed + +## Other stakeholders + +From [who to ask for review](https://www.w3.org/Guide/documentreview/#who_to_ask_for_review): +>Horizontal reviews [...] are only a subset of a full wide review, which must also include other stakeholders including Web developers, technology providers and implementers not active in the Working Group, external groups and standards organizations working on related areas, etc. + +`; function addGitHubIssueButton() { document.querySelector('#githubissue button').addEventListener('click', createGitHubIssue); document.getElementById('githubissue').hidden = false; } - -function createGitHubIssue(event) { +async function createGitHubIssue(event) { event.preventDefault(); const value = document.getElementById('repository').value.trim(); - const match = value.match(/github\.com\/(.*?)\/?$/); - const repo = match ? match[1] : value; - if (!repo.match(/^[^\s\/]+\/[^\s\/]+$/)) { + let match = value.match(/github\.com\/(.*?)\/?$/); + match = (match ? match[1] : value).match(/^([^\s\/]+)\/([^\s\/]+)$/); + if (!match) { console.warn('Invalid repository name entered', value); window.alert(`Invalid repository name: "${value}".\nExpected format: "owner/repo", e.g. "w3c/foobar".`); return; } - + const repo = { owner: match[1], name: match[2] }; + console.log(`Creating GitHub issue for repository: ${repo.owner}/${repo.name}`); + const title = encodeURIComponent('Seek wide review'); - const body = encodeURIComponent(generateGitHubIssueBody()); - window.open(`https://github.com/${repo}/issues/new?title=${title}&body=${body}`); + try { + const body = encodeURIComponent(await generateGitHubIssueBody(repo)); + window.open(`https://github.com/${repo.owner}/${repo.name}/issues/new?title=${title}&body=${body}`); + } catch (error) { + console.error('Error creating GitHub issue:', error); + window.alert('Failed to create GitHub issue. Please try again later.'); + } } +async function generateGitHubIssueBody(repo) { -function generateGitHubIssueBody() { const dl = document.querySelector('#how-to-get-horizontal-review ~ dl'); if (!dl) { console.error('Could not find right anchor in "How to get horizontal review" section'); } const bullets = [...dl.querySelectorAll('dt')].map(dt => { + const horizontal = dt.dataset.type || 'unknown'; const dd = dt.nextElementSibling; if (dd.tagName !== 'DD') { console.error('Could not find a DD tag after DT', dt); return; } - const subContents = [...dd.querySelectorAll('.step')].map(el => ` - [ ] ${el.innerHTML}`); + const subContents = [...dd.querySelectorAll('.step')].map(el => `- [ ] ${html2Markdown(el)}`); + + const after = `- [ ] Address [${horizontal}-needs-resolution](https://github.com/${repo.owner}/${repo.name}/labels/${horizontal}-needs-resolution) issues +- [ ] Consider [${horizontal}-tracker](https://github.com/${repo.owner}/${repo.name}/labels/${horizontal}-tracker) issues +- [ ] feedback integrated +- [ ] Review confirmed completed`; - return ` - ${dt.textContent}\n${subContents.join('\n')}`; + return `🔴 **${dt.textContent}**\n\n${subContents.join('\n')}\n${after}\n`; }); + + const group = await findGroup(repo); - return `This is a meta issue to track wide review steps for the specification. -See [How to do wide review](https://www.w3.org/guide/documentreview/#who-to-ask-for-wide-review) for details. + return template + .replace('{{HORIZONTAL_GROUPS_LIST}}', bullets.join('\n')) + .replace(/YOURGROUP/g, (group) ? `${group}/charters/active/#coordination` : ''); +} -- [ ] the groups listed in the WG's charter, especially those who manage dependencies -- [ ] the groups jointly responsible for a particular document (if any). -- the horizontal groups: -${bullets.join('\n')} -- Other outreach (if applicable) -`; +function html2Markdown(element) { + let markdown = element.innerHTML; + markdown = markdown.replace(/(.*?)<\/strong>/g, '**$1**'); + markdown = markdown.replace(/(.*?)<\/em>/g, '*$1*'); + markdown = markdown.replace(/ rel="[^"]+"/g, ''); + markdown = markdown.replace(/ class="[^"]+"/g, ''); + markdown = markdown.replace(/(.*?)<\/a>/g, '[$2]($1)'); + markdown = markdown.replace(/<[^>]+>/g, ''); + return markdown.trim(); } + +async function findGroup(repo) { + const repoInfo = (await repositories).find(r => r.name.toLowerCase() === repo.name.toLowerCase() && r.owner.login.toLowerCase() === repo.owner.toLowerCase()); + const groups = (repoInfo && repoInfo.w3cjson) ? repoInfo.w3cjson.group : null; + + if (groups && groups.length > 0) { + const wgs = groups.filter(g => g.startsWith('wg/')); + const igs = groups.filter(g => g.startsWith('ig/')); + if (wgs.length > 0) { + return wgs[0]; + } else if (igs.length > 0) { + return igs[0]; + } + } + return null; +} + +if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', addGitHubIssueButton); +} else { + addGitHubIssueButton(); +} \ No newline at end of file diff --git a/documentreview/index.md b/documentreview/index.md index f665b1b5..b65e9381 100644 --- a/documentreview/index.md +++ b/documentreview/index.md @@ -72,86 +72,86 @@ When you have published a First Public Working Draft, you should work through av The meaning of "Long enough" depends on how many changes there are, how clearly you have explained them, and how much discussion is needed to resolve issues. Pointing to 14 concise points for a small spec means a short time if they are simple fixes, pointing to 900 diffs from commits and hoping people understand them in a 300 page spec means it will take a **long** time to get review, and potentially a long time to also discuss and agree on how to solve the issues. If you have effectively identified issues for review during development and received feedback on them, the review time will probably be shorter. Horizontal review groups sometimes get bogged down; planning in advance is useful.
-
Accessibility
+
Accessibility
- Work through this questionnaire then - request a review via GitHub from APA + Work through this questionnaire then + request a review via GitHub from APA
Show useful links +
-
Architecture
+
Architecture
- Ask the TAG for review; see how to work with the TAG. - If you are developing javascript APIs you may also want to ask public-script-coord@w3.org, a technical discussion list shared by W3C and ECMA's TC 39. + Work through Specification Design Reviews then + request a review via GitHub from the TAG + If you are developing javascript APIs you may also want to ask public-script-coord@w3.org, a technical discussion list shared by W3C and ECMA's TC 39.
Show useful links -
-
+ + -
Internationalization
+
Internationalization
- Read the Request a review page, then - work through the Short Checklist, then - request a review via GitHub. + Read the Request a review page, then + work through the Short Checklist, then + request a review via GitHub.
Show useful links +
-
Privacy
+
Privacy
- Write a "Privacy Considerations" section for your document, taking into account the Self-Review Questionnaire: Security and Privacy, Mitigating Browser Fingerprinting in Web Specifications, and RFC6973 then - request a review via GitHub from the Privacy Working Group. + Write a "Privacy Considerations" section for your document, taking into account the Self-Review Questionnaire: Security and Privacy, Mitigating Browser Fingerprinting in Web Specifications, and RFC6973 then + request a review via GitHub from the Privacy Working Group.
Show useful links
-
Security
+
Security
- Write a "Security Considerations" section for your document, taking into account the Self-Review Questionnaire: Security and Privacy, then - request a review via GitHub + Write a "Security Considerations" section for your document, taking into account the Self-Review Questionnaire: Security and Privacy, then + request a review via GitHub
Show useful links +
@@ -247,4 +247,4 @@ See the [Document Review Dashboard](https://www.w3.org/wiki/Dashboard#Document_R background: #e2edfe; } - + From b32015c0b7989c902259cb628b12638c2dd1e71d Mon Sep 17 00:00:00 2001 From: plehegar Date: Tue, 3 Feb 2026 19:16:17 -0500 Subject: [PATCH 2/6] Allow repo= as a URL parameter --- documentreview/create-github-issue.js | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/documentreview/create-github-issue.js b/documentreview/create-github-issue.js index 59456ff1..64c0b4cd 100644 --- a/documentreview/create-github-issue.js +++ b/documentreview/create-github-issue.js @@ -36,6 +36,11 @@ From [who to ask for review](https://www.w3.org/Guide/documentreview/#who_to_ask function addGitHubIssueButton() { document.querySelector('#githubissue button').addEventListener('click', createGitHubIssue); + const params = new URLSearchParams(window.location.search); + const repo = params.get('repo'); + if (repo) { + document.getElementById('repository').value = repo; + } document.getElementById('githubissue').hidden = false; } From 30b24f3c70a04962bec875edde593227c22ac352 Mon Sep 17 00:00:00 2001 From: Philippe Le Hegaret Date: Thu, 5 Feb 2026 15:07:45 -0500 Subject: [PATCH 3/6] Update documentreview/create-github-issue.js MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: François Daoust --- documentreview/create-github-issue.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentreview/create-github-issue.js b/documentreview/create-github-issue.js index 64c0b4cd..f3350f3b 100644 --- a/documentreview/create-github-issue.js +++ b/documentreview/create-github-issue.js @@ -71,7 +71,7 @@ async function generateGitHubIssueBody(repo) { const dl = document.querySelector('#how-to-get-horizontal-review ~ dl'); if (!dl) { - console.error('Could not find right anchor in "How to get horizontal review" section'); + throw new Error('Could not find right anchor in "How to get horizontal review" section'); } const bullets = [...dl.querySelectorAll('dt')].map(dt => { From 00eaa25c5a18bc3fe9e3d125cbf1fafedde7566d Mon Sep 17 00:00:00 2001 From: Philippe Le Hegaret Date: Thu, 5 Feb 2026 15:07:55 -0500 Subject: [PATCH 4/6] Update documentreview/create-github-issue.js MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: François Daoust --- documentreview/create-github-issue.js | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentreview/create-github-issue.js b/documentreview/create-github-issue.js index f3350f3b..4b262d5d 100644 --- a/documentreview/create-github-issue.js +++ b/documentreview/create-github-issue.js @@ -78,8 +78,7 @@ async function generateGitHubIssueBody(repo) { const horizontal = dt.dataset.type || 'unknown'; const dd = dt.nextElementSibling; if (dd.tagName !== 'DD') { - console.error('Could not find a DD tag after DT', dt); - return; +throw new Error('Could not find a DD tag after DT in one of the horizontal sections'); } const subContents = [...dd.querySelectorAll('.step')].map(el => `- [ ] ${html2Markdown(el)}`); From 4969dbcef74dc462868e86d4b6edd5f9a9c0f714 Mon Sep 17 00:00:00 2001 From: Philippe Le Hegaret Date: Thu, 5 Feb 2026 15:08:25 -0500 Subject: [PATCH 5/6] Update documentreview/create-github-issue.js MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: François Daoust --- documentreview/create-github-issue.js | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/documentreview/create-github-issue.js b/documentreview/create-github-issue.js index 4b262d5d..4438f3c7 100644 --- a/documentreview/create-github-issue.js +++ b/documentreview/create-github-issue.js @@ -1,3 +1,15 @@ +/** + * Script that adds a button to the Document review page that readers may use + * to draft a meta issue in the GitHub repository of their choice to track wide + * review steps. + * + * The script expects to find specific anchors in the Document review page, + * including a definition list for each horizontal flagged with a `data-type` + * attribute whose value matches the prefix used in GitHub labels + * `[foo]-needs-resolution` and `[foo]-tracker`, with individual steps flagged + * as such. + */ + const repositories = fetch('https://w3c.github.io/groups/repositories.json').then(res => res.ok ? res.json() : []) .catch(() => []); From 2940d1192d5df02d9aed3320af57cd952b2224e7 Mon Sep 17 00:00:00 2001 From: plehegar Date: Thu, 5 Feb 2026 15:21:47 -0500 Subject: [PATCH 6/6] Github ttemplate: use data-step and remove markers --- documentreview/create-github-issue.js | 12 +++--------- documentreview/index.md | 24 ++++++++++++------------ 2 files changed, 15 insertions(+), 21 deletions(-) diff --git a/documentreview/create-github-issue.js b/documentreview/create-github-issue.js index 4438f3c7..f2d6fc64 100644 --- a/documentreview/create-github-issue.js +++ b/documentreview/create-github-issue.js @@ -18,12 +18,6 @@ const template = `# Wide review tracker for a specification This is a meta issue to track wide review steps for the specification. See [How to do wide review](https://www.w3.org/guide/documentreview/#who-to-ask-for-wide-review) for details. ->Legend: ->🔴 Review request not submitted ->🟡 Review request submitted ->🔵 Review feedback received ->🟢 Review closed as completed - ## Horizontal groups An important part of wide review is horizontal review from W3C's [key horizontal groups](https://www.w3.org/guide/documentreview/#how-to-get-horizontal-review) listed below. @@ -33,7 +27,7 @@ An important part of wide review is horizontal review from W3C's [key horizontal The [charter](https://www.w3.org/groups/YOURGROUP) contains a list of dependency groups. If you skip one of those, simply provide a rational. -🔴 ?? Group: +### ?? Group: - [ ] feedback requested - [ ] feedback received @@ -93,14 +87,14 @@ async function generateGitHubIssueBody(repo) { throw new Error('Could not find a DD tag after DT in one of the horizontal sections'); } - const subContents = [...dd.querySelectorAll('.step')].map(el => `- [ ] ${html2Markdown(el)}`); + const subContents = [...dd.querySelectorAll('*[data-step]')].map(el => `- [ ] ${html2Markdown(el)}`); const after = `- [ ] Address [${horizontal}-needs-resolution](https://github.com/${repo.owner}/${repo.name}/labels/${horizontal}-needs-resolution) issues - [ ] Consider [${horizontal}-tracker](https://github.com/${repo.owner}/${repo.name}/labels/${horizontal}-tracker) issues - [ ] feedback integrated - [ ] Review confirmed completed`; - return `🔴 **${dt.textContent}**\n\n${subContents.join('\n')}\n${after}\n`; + return `### **${dt.textContent}**\n\n${subContents.join('\n')}\n${after}\n`; }); const group = await findGroup(repo); diff --git a/documentreview/index.md b/documentreview/index.md index b65e9381..45ba7ec9 100644 --- a/documentreview/index.md +++ b/documentreview/index.md @@ -74,8 +74,8 @@ The meaning of "Long enough" depends on how many changes there are, how clearly
Accessibility
- Work through this questionnaire then - request a review via GitHub from APA + Work through the FAST Checklist then + request a review via GitHub from APA
Show useful links