Skip to content
This repository has been archived by the owner on Jun 30, 2018. It is now read-only.

Tending to SC Proposals

Jump to bottom
Andrew Kirkpatrick edited this page Mar 27, 2017 · 7 revisions

To make sure that people always know where the current version of Success Criteria proposals is, we ask that SC managers do the following for each issue that they are in charge of monitoring:

I expect that this will take you 3-5 minutes per issue. If you run into difficulty, please don’t feel hesitant in reaching out to Andrew, Josh, or Michael for help.

Setting up links to viewable and editable versions

The “figure it out yourself” version of the instructions

Look at the top of the initial comment for Issue 2 (https://github.com/w3c/wcag21/issues/2) and do the same for your issue, being careful to select the right branch for the URI’s you use (see step 2 in the longer instructions).

What is needed is a section titled "Current versions of SC and Definitions" at the top of the first comment in the issue, followed by these links (all of the links point to locations in the branch dedicated to the issue):

  • Link to SC for viewing | link to SC for editing
  • Link to definition1 for viewing | link to definition1 for editing
  • Link to definition2 for viewing | link to definition2 for editing
  • Link to full guideline in the draft guideline

The “step-by-step” version

Issue 2 for “Change of Content” is used as an example throughout the steps.

  1. Open your issue in a browser window- you will need to refer to this page and eventually make some edits.
  2. In a different tab or browser window, identify the branch for your issue at https://github.com/w3c/wcag21. (For Issue 2 it is “change-of-content_ISSUE-2”). Switch to that branch.
  3. Go to the guidelines directory and then into the SC directory, and then into the “21” directory.
  4. Find the HTML file that matches the first part of the branch name. Click on that file and copy the URI of the page to a separate document.
  5. Check that the URI you copied contains the correct branch. (for Issue 2, the URI is https://github.com/w3c/wcag21/blob/change-of-content_ISSUE-2/guidelines/sc/21/change-of-content.html – note that after the “blob” part of the URI the URI includes a match to the correct branch name).
  6. Look at the issue you are managing (in the other browser window) - if there are definitions being defined with the SC proposal, continue to the next step. If not, skip to step 9.
  7. Back up out of the “21” and “SC” directories, and go into the “terms” directory and into the “21” directory.
  8. Find the HTML file (or files if the proposed SC has multiple definitions) and copy the URI for each term into a separate document.
  9. Once you have the URIs for the SC and each definition, you can close the browser window for the branch but keep the issue window open. We are ready for the changes to the issue.
  10. You should have permissions to edit the original issue description. We hope that this will be the last time we do this. Click on the pencil icon at the top and right side of the issue
  11. On the first line of the issue description put:

## Current versions of SC and Definitions

  1. On the second line you are going to use the Github syntax for links to provide links to the SC - the best thing to do is copy and paste this example and then modify it. Paste the following:

- [SC for viewing](https://rawgit.com/w3c/wcag21/change-of-content_ISSUE-2/guidelines/sc/21/change-of-content.html) | [SC for editing](https://github.com/w3c/wcag21/blob/change-of-content_ISSUE-2/guidelines/sc/21/change-of-content.html)

  1. Now edit the two URI – the second one is for the link to the editing version of the SC and this is the first link you copied in step #4 above. The URI for the “SC for viewing” is the same URI except that “github.com” is replaced with “rawgit.com” and the “blob/“ is removed from the URI.
  2. On the third line (and possibly on additional lines if there is more than one definition) we will provide the definition links. Again, copy and paste the following and then edit the URI as in step #13, except that you will use the link or links to the definitions that you copied in step #8. You will also need to update the link text from "Change of Content" to your glossary term, two times.

- [Change of Content definition for viewing](https://rawgit.com/w3c/wcag21/change-of-content_ISSUE-2/guidelines/terms/21/change-of-content.html) | [Change of Content definition for editing](https://github.com/w3c/wcag21/blob/change-of-content_ISSUE-2/guidelines/terms/21/change-of-content.html)

  1. Finally, on the next line paste the following and replace the “#change-of-content” with the file name from the URL copied in step #4 (for issue 2 it would be "change-of-content.html” but strip off the “.html”. You will also need to adjust the branch from "change-of-content_ISSUE-2" to the correct branch name. This will provide a link to the proposed SC in the document in context. - [SC in full draft guideline](https://rawgit.com/w3c/wcag21/change-of-content_ISSUE-2/guidelines/#change-of-content)

  2. Click “update comment”.

  3. Test your links to make sure they work - if blank pages or commented out code appears, see the next section.

Help!

If this is too confusing or you are otherwise having trouble, please try at least to email the links copied in steps 4 and 8 to Andrew, Josh, and Michael.

Updating the SC and Definition markup

Here’s an example of an issue that shows commented out code (at least it does right now, I expect it will get updated soon): https://github.com/w3c/wcag21/blob/extra-help_ISSUE-45/guidelines/sc/21/extra-help.html

And if you view the rawgit.com version you see a blank page (because the code is all commented out): https://rawgit.com/w3c/wcag21/extra-help_ISSUE-45/guidelines/sc/21/extra-help.html

For the SC itself, the commented code will look like this:

<!--
<section class="sc proposed">
   <h4>{handle}</h4>
   <p class="conformance-level"></p>
   <p class="change">Proposed</p>
   <p>{SC text}</p>
</section>
-->

Steps to Update the SC text with the current draft text:

  1. Go to the page with the commented code by following the link from the issue. (e.g. https://github.com/w3c/wcag21/blob/extra-help_ISSUE-45/guidelines/sc/21/extra-help.html)
  2. Click on the pencil on the right side of the page to edit the code.
  3. Remove the HTML comment indicators (on line 1 and line 8)
  4. Replace “{handle}” with the SC title. All Words Get Capitalized (Even In Parentheses).
  5. Add “A”, “AA”, or “AAA” to the paragraph with the “conformance-level” class.
  6. Replace “{SC text}” with the text of the SC.
  • If the SC is longer than a single paragraph you will need to add paragraphs or lists or whatever is needed to represent the SC.
  • To refer to a linked definition, just put wrap the term in an anchor element, like <a>this</a>. It seems wrong, but it is all we need to generate the link properly.
  • Use the FPWD as a reference if you have specific coding questions, or ask AWK or Michael.

  1. To save the changes, find the “commit changes” section at the bottom of the page, add a commit message (e.g. Initial addition of proposed SC text”), make sure the “commit directly to the [whatever] branch” radio button is selected, and click the “commit changes” button.

  2. In the same branch as the SC (in this case it would be the "extra-help_ISSUE-45" branch), locate the guidelines directory and open the index.html file.

  3. Click on the pencil icon to edit the file.

  4. Locate the reference to the SC's HTML file. The easiest way is likely with the browser's find command. Once located, it may show commented code:

    <!-- <section data-include="sc/21/minimize-user-errors.html" data-include-replace="true"></section> -->

  5. Remove the comments, add a commit message at the bottom of the page and commit the changes to the current branch by clicking the "commit changes" button.

Steps to update the definition text

For a missing definition, the commented code will look like this:

<!--
<dt class="proposed"><dfn>{term}</dfn></dt>
<dd class="proposed">
   <p class="change">Proposed</p>
   <p>{term}</p>
</dd>
-->

Steps to update definitions:

  1. Go to the page with the commented code.

  2. Click on the pencil on the right side of the page to edit the code.

  3. Remove the HTML comment indicators (on line 1 and line 7)

  4. Replace the “{term}” in line 2 with the word being defined. no capital letters please.

  5. Add “A”, “AA”, or “AAA” to the paragraph with the “conformance-level” class.

  6. Replace the “{term}” in line 5 with the text of the definition. For definitions that have more than one paragraph, add paragraphs as needed (same for any needed list markup).

  7. To save the changes, find the “commit changes” section at the bottom of the page, add a commit message (e.g. "Initial addition of definition text" , make sure the “commit directly to the [whatever] branch” radio button is selected, and click the “commit changes” button.

  8. Repeat for additional definitions associated with this proposed SC.

  9. In the same branch as the SC (in this case it would be the "extra-help_ISSUE-45" branch), locate the guidelines directory and open the index.html file.

  10. Click on the pencil icon to edit the file.

  11. Locate the reference to the SC's glossary file (or files if more than one definition is used). The easiest way is likely with the browser's find command. Once located, it may show commented code:

    <!-- <dt data-include="terms/21/important-information.html" data-include-replace="true"></dt> -->

  12. Remove the comments, add a commit message at the bottom of the page and commit the changes to the current branch by clicking the "commit changes" button.

Clone this wiki locally