Skip to content

Commit

Permalink
Add button to create a meta-issue on GitHub
Browse files Browse the repository at this point in the history 
This adds a button to the "How to get horizontal review" section to generate
a meta-issue to track horizontal review steps in a GitHub repository, following
a suggestion made by @anssiko in:
w3c/openscreenprotocol#284 (comment)

Some notes:
- Taking that approach instead of creating an issue template, as I believe that
the issue template would be seen whenever someone tries to create a new issue
and the horizontal reviews issue will only be useful once or twice per
specification.
- Sub-details sections are not included because they would grow the length of
the body beyond what can be passed to GitHub in a query string
- To keep script simple, actual steps need to be made explicit by enclosing the
prose for each step into a `<span class="step">` construct.
  • Loading branch information
@tidoust
tidoust committed Jun 7, 2021
1 parent adbce40 commit 8ee3ea9
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 7 deletions.
49 changes: 49 additions & 0 deletions createGitHubIssue.js
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
window.addEventListener('load', addGitHubIssueButton);


function addGitHubIssueButton() {
document.querySelector('#githubissue button').addEventListener('click', createGitHubIssue);
document.getElementById('githubissue').hidden = false;
}


function createGitHubIssue() {
const value = document.getElementById('repository').value.trim();
const match = value.match(/github\.com\/(.*?)\/?$/);
const repo = match ? match[1] : value;
if (!repo.match(/^[^\s\/]+\/[^\s\/]+$/)) {
console.warn('Invalid repository name entered', value);
window.alert(`Invalid repository name: "${value}".\nExpected format: "owner/repo", e.g. "w3c/documentreview".`);
return;
}

const title = encodeURIComponent('Seek horizontal reviews');
const body = encodeURIComponent(generateGitHubIssueBody());
window.open(`https://github.com/${repo}/issues/new?title=${title}&body=${body}`);
}


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 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}`);

return `- ${dt.textContent}\n${subContents.join('\n')}`;
});

return `This is a meta issue to track horizontal review steps for the specification.
See [How to do wide review](https://www.w3.org/Guide/documentreview/#how_to_get_horizontal_review) for details.
${bullets.join('\n')}
`;
}
38 changes: 31 additions & 7 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,9 @@ <h2><a href="#how_to_get_horizontal_review">How to get horizontal review</a></h2
<p>When you have published a First Public Working Draft, you should work through available "self-review" materials and request review of your results in at least the following areas. <em>Long enough</em> before you request a transition to CR, you should do the same again, identifying substantive specification changes since the first review. </p><p>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 <strong>long</strong> 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.</p>
<dl>
<dt>Accessibility</dt>
<dd>Work through <a rel="nofollow" class="external text" href="https://w3c.github.io/apa/fast/checklist.html">this questionnaire</a> then <a rel="nofollow" class="external text" href="https://github.com/w3c/a11y-request/issues/new/choose">request a review via GitHub</a> from <a rel="nofollow" class="external text" href="https://www.w3.org/WAI/APA/">APA</a>
<dd>
<span class="step">Work through <a rel="nofollow" class="external text" href="https://w3c.github.io/apa/fast/checklist.html">this questionnaire</a></span> then
<span class="step"><a rel="nofollow" class="external text" href="https://github.com/w3c/a11y-request/issues/new/choose">request a review via GitHub</a> from <a rel="nofollow" class="external text" href="https://www.w3.org/WAI/APA/">APA</a></span>
<details>
<summary>Show useful links</summary>
<ul><li> groups
Expand All @@ -76,7 +78,9 @@ <h2><a href="#how_to_get_horizontal_review">How to get horizontal review</a></h2


<dt>Architecture</dt>
<dd>Ask the <a rel="nofollow" class="external text" href="https://www.w3.org/2001/tag/">TAG</a> for review; see <a rel="nofollow" class="external text" href="https://tag.w3.org/workmode/">how to work with the TAG</a>. If you are developing javascript APIs you may also want to ask <a rel="nofollow" class="external text" href="mailto:[email protected]">[email protected]</a>, a technical discussion list shared by W3C and ECMA's TC 39.
<dd>
<span class="step">Ask the <a rel="nofollow" class="external text" href="https://www.w3.org/2001/tag/">TAG</a> for review; see <a rel="nofollow" class="external text" href="https://tag.w3.org/workmode/">how to work with the TAG</a></span>.
<span class="step">If you are developing javascript APIs you may also want to ask <a rel="nofollow" class="external text" href="mailto:[email protected]">[email protected]</a>, a technical discussion list shared by W3C and ECMA's TC 39</span>.
<details>
<summary>Show useful links</summary>
<ul><li> groups
Expand All @@ -93,7 +97,10 @@ <h2><a href="#how_to_get_horizontal_review">How to get horizontal review</a></h2


<dt>Internationalisation</dt>
<dd>Read the <a rel="nofollow" class="external text" href="https://www.w3.org/International/review-request">Request a review</a> page, then work through the <a rel="nofollow" class="external text" href="https://w3c.github.io/i18n-drafts/techniques/shortchecklist">Short Checklist</a>, then <a rel="nofollow" class="external text" href="https://github.com/w3c/i18n-request/issues/new/choose">request a review via GitHub</a>.
<dd>
<span class="step">Read the <a rel="nofollow" class="external text" href="https://www.w3.org/International/review-request">Request a review</a> page</span>, then
<span class="step">work through the <a rel="nofollow" class="external text" href="https://w3c.github.io/i18n-drafts/techniques/shortchecklist">Short Checklist</a></span>, then
<span class="step"><a rel="nofollow" class="external text" href="https://github.com/w3c/i18n-request/issues/new/choose">request a review via GitHub</a></span>.
<details>
<summary>Show useful links</summary>
<ul><li> groups
Expand All @@ -110,7 +117,9 @@ <h2><a href="#how_to_get_horizontal_review">How to get horizontal review</a></h2


<dt>Privacy</dt>
<dd>Write a "Privacy Considerations" section for your document, taking into account the <a rel="nofollow" class="external text" href="https://w3ctag.github.io/security-questionnaire/">Self-Review Questionnaire: Security and Privacy</a>, <a rel="nofollow" class="external text" href="https://w3c.github.io/fingerprinting-guidance/">Mitigating Browser Fingerprinting in Web Specifications</a>, and <a rel="nofollow" class="external text" href="https://tools.ietf.org/html/rfc6973">RFC6973</a> then <a rel="nofollow" class="external text" href="https://github.com/w3cping/privacy-request/issues/new/choose">request a review via GitHub</a> from the <a rel="nofollow" class="external text" href="https://www.w3.org/Privacy/">Privacy Interest Group</a>.
<dd>
<span class="step">Write a "Privacy Considerations" section for your document, taking into account the <a rel="nofollow" class="external text" href="https://w3ctag.github.io/security-questionnaire/">Self-Review Questionnaire: Security and Privacy</a>, <a rel="nofollow" class="external text" href="https://w3c.github.io/fingerprinting-guidance/">Mitigating Browser Fingerprinting in Web Specifications</a>, and <a rel="nofollow" class="external text" href="https://tools.ietf.org/html/rfc6973">RFC6973</a></span> then
<span class="step"><a rel="nofollow" class="external text" href="https://github.com/w3cping/privacy-request/issues/new/choose">request a review via GitHub</a> from the <a rel="nofollow" class="external text" href="https://www.w3.org/Privacy/">Privacy Interest Group</a></span>.
<details>
<summary>Show useful links</summary>
<ul><li>groups
Expand All @@ -129,7 +138,9 @@ <h2><a href="#how_to_get_horizontal_review">How to get horizontal review</a></h2


<dt>Security</dt>
<dd>Write a "Security Considerations" section for your document, taking into account the <a rel="nofollow" class="external text" href="https://w3ctag.github.io/security-questionnaire/">Self-Review Questionnaire: Security and Privacy</a>, then <a rel="nofollow" class="external text" href="https://github.com/w3c/security-request/issues/new/choose">request a review via GitHub</a>
<dd>
<span class="step">Write a "Security Considerations" section for your document, taking into account the <a rel="nofollow" class="external text" href="https://w3ctag.github.io/security-questionnaire/">Self-Review Questionnaire: Security and Privacy</a></span>, then
<span class="step"><a rel="nofollow" class="external text" href="https://github.com/w3c/security-request/issues/new/choose">request a review via GitHub</a></span>

<details>
<summary>Show useful links</summary>
Expand All @@ -146,14 +157,25 @@ <h2><a href="#how_to_get_horizontal_review">How to get horizontal review</a></h2


<dt>Groups listed in your charter</dt>
<dd>If there are groups listed in your charter as depending on some specification, you should ask them too.</dd>
<dd><span class="step">If there are groups listed in your charter as depending on some specification, you should ask them too</span>.</dd>



<dt> General announcement</dt>
<dd>Use <a rel="nofollow" class="external text" href="mailto:[email protected]">[email protected]</a> for general announcements regarding wide and horizontal reviews. (Sending an email to this list alone is not sufficient to trigger horizontal reviews. You will still need to formally request review from the Horizontal Groups, as described above.)</dd>
<dd><span class="step">Use <a rel="nofollow" class="external text" href="mailto:[email protected]">[email protected]</a> for general announcements regarding wide and horizontal reviews. (Sending an email to this list alone is not sufficient to trigger horizontal reviews. You will still need to formally request review from the Horizontal Groups, as described above.)</span></dd>
</dl>

<details id="githubissue" hidden>
<summary>Generate a meta-issue to track horizontal review steps in a GitHub repository</summary>
<p>You may find it useful to create an issue in the GitHub repository that hosts a specification that needs to get horizontal reviews to track the different steps involved to request these reviews. Fill the name of your GitHub repository in the field below and hit the "Create GitHub issue" button to open the "new issue" form on the specified GitHub repository, with the issue's body pre-filled with horizontal review steps as a list of checkboxes.</p>
<p>
<label for="repository">GitHub repository where issue should be created (format: <code>owner/repo</code>):</label>
<br/><input type="text" name="repository" id="repository" placeholder="Repo name, e.g. w3c/documentreview">
<br/><button>Create GitHub issue</button>
</p>
<p>Note: You will be able to edit the issue's title and body before it gets created.</p>
</details>

<p>You should familiarize yourself with the rest of this document. This section is just a quick reminder for when you are in the middle of doing the work.</p>
</section>

Expand Down Expand Up @@ -337,4 +359,6 @@ <h2><a href="#resources">Resources</a></h2>

<div id="versionInfo"><small>Last updated 31 Jul 2020. See the <a href="https://github.com/w3c/documentreview/commits/gh-pages/index.html">commit history</a>.</small></div>

<script type="text/javascript" src="createGitHubIssue.js"></script>

</body></html>
12 changes: 12 additions & 0 deletions style.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,3 +51,15 @@ h2 a {
text-decoration: none;
}

#githubissue {
width: 70%;
margin: auto;
border-bottom: 3px solid #005A9C;
padding: 1em 1em;
background: #e2edfe;
}

#githubissue input[type=text] {
width: 70%;
margin-bottom: 0.5em;
}

0 comments on commit 8ee3ea9

Please sign in to comment.