WCAG 2 Task Force process
Contents:
Predominantly informative WCAG 2.x content is worked on by The "WCAG 2" Task Force within the Accessibility Guidelines Working group.
Compared to other task forces, substantially more issues exist, and a greater number of new issues are created, so we have tried to optimize the process for efficient and transparent working.
Most of the work gets done on GitHub; if there is an impasse, or decisions needed by AGWG, it will be escalated to a WG meeting.
As a very brief overview:
- Issues or Pull Requests (PRs) are raised.
- Someone takes on issue/PR as an assignment.
- When drafted, the Task Force reviews it.
- When agreed, the Accessibility Guidelines Working Group review it.
- If either stage is not approved, it goes back to drafting.
- If approved by both, it is merged / closed.
- Review the new issues (both), PRs (Mike), and discussions (Bruce) opened during the week, perform a light triage, add labels or comments as appropriate. See Issue triage for a breakdown.
- Monitor stale items on the board and encourage the progression of issues.
- Assess the items in Draft. Where a PR is commented as closing an issue (e.g., "Closes #issueNumber") the PR should be add to the Project, and the Issue should be removed. If the PR does not close the issue, both the PR and Issue remain on the Project board.
- Prepare agenda for Friday call, where it deviates from the standing agenda outlined in a section below
- Handle the merging of WG-approved PRs, and the recording of errata.
- Periodically review github Issues labelled with certain criteria (e.g., "Inactive, close soon"). Issues that do have not been replied in over a year may be closed without adding labels.
- Check that issues closed on the repo are properly captured in the project, where effort of TF members was involved (e.g., search for "is:issue is:closed no:project", and where no PR is in milestone column.)
- Examine the To Do issues on the project board.
- If they see one they are interested in, self-assign it.
- When they begin working on it, change its status to In Progress.
- Curate PRs they created to completion, including incorporating feedback from WG review.
- when ready to be reviewed by the group, change status changed to Drafted
- label them as Bug Fix, Editorial, or Substantive
- Review and comment on other’s items with a Drafted status, including self-assigning as a Reviewer.
- Appoint a scribe (often Co-facilitator for now).
- The facilitators will follow a prepared agenda, or where there is not one prepared, use the following standing agenda.
- Review ‘For discussion’ items
- Review ‘Drafted’ items (30 min), either:
- move back to In progress, with more work to do
- move to Ready for approval, if there is general agreement the issue is sufficiently resolved
- leave in Drafted, if discussion was not concluded satisfactorily
- Review issues closed and project items closed.
- Review ‘To do’.
- Time permitting, items of interest to participants, including open discussions.
- Scribe distribute notes from meeting to TF list: [email protected]
- Biweekly on Mondays, compile and distribute Ready for approval items and Fully reviewed Bug fixes for AG information (see Approval process for change, below); move Ready for approval items to Sent for WG approval.
The project board uses the following columns for managing the status of issues/PRs:
- To do: Items picked by the facilitators to prioritize items from the backlog.
- In progress: Items being actively worked-on, must already be assigned to someone.
- Drafted: Items ready for TF review, things to discuss at the next meeting.
- Ready for approval: Items queued for AG approval.
- Sent for WG approval: Items added to the email to the working group for approval. They stay in this column for two weeks, and are moved during the 2-week window or when it is finished.
- For discussion: TF reviewed items that did not reach consensus (and therefore were not merged), to be raised at a synchronous meeting.
- Fully reviewed: Items ready to be merged (or in case of Response Only, to be modified to "Official Working Groups Response"). Bug fixes agreed on by the TF, and issues/PRs reviewed by the AG. Can be listed in bi-weekly mail out, then moved to Done.
- Done: Everything merged or completed.
Generally issues/PRs go from left to right, but may go back one or more steps if they need adjustment.
- Send a summary email every 2 weeks (generally on a monday). See Email template
- To the TF list, CCing the AG list.
- Any follow-up discussion should be on the TF list only.
- Each email contains all the items up for approval, and all the items merged since the last email (both Bug Fixes and approved Editorial and Substantive changes).
- Each change is categorized into one of the four “Levels of issue/change,” below.
- The ‘bug fixes’ category will be merged already, but it would list the PRs of the changes for transparency.
- AG has two weeks to comment on the PR or topic.
- We will aim to deal with as much as possible asynchronously.
- The Friday meeting can be time-boxed to discuss initial feedback, and we can make updates to improve the chance of approval.
- Issues/PRs which have had at least 5 people give a thumbs-up or review (either through the github assign/review process or discussed on a task force call), for which no concrete objections remain, will be considered to have consensus.
- Anything which cannot be resolved (get consensus) in the github thread will be placed on the For discussion column and included in a meeting agenda
- Any proposed normative change will be tagged as both Normative and Erratum Raised and brought to an AG meeting.
-
Normative: Changes to the normative text of the specification, as defined in 5.1 Interpreting Normative Requirements, which would individually be escalated to the chairs as a Normative Erratum Raised and go through a CFC process.
-
Substantive: Changes that meaningfully add or alter existing guidance. New techniques, new sections in documents, concepts being added or emphasized. This includes if there is a total restructuring of an informative document so that it might not be obvious to a casual observer that meaning has not changed. As well, any previously proposed substantive changes which received divergent feedback and have been redrafted.
-
Editorial: Improvements that are not intended to alter interpretation. Re-phrasing that clearly does not change meaning, but aims to improve readability or understanding of informative documents. Examples include adding headings, adding or changing sentences, reordering sentences or paragraphs. This includes previously proposed substantive or editorial changes approved by AG and for which only minor changes were needed to be resolved. Note that changes to examples or notes within the technical standard are tagged with Erratum Raised, but do not constitute normative changes, so do not also get the Normative tag (instead, Editorial). Examples and notes in definitions, for example, are not normative, but do need to go through a specific adoption and merge process, and also need to be added as errata (see Errata changes, below).
-
Bug fix: Trivial editorial corrections (e.g., typos, spelling, subject-verb agreement, punctuation), style consistency, code syntax corrections, broken links, etc. will be reported in the PR, but the work will be done as the errors are found.
-
Response-Only: Draft comment on issue that does not result in a change to non-normative content or interpretation. The established process for this is that the words "Draft Working Group Response" appear in bold at the top of the comment that contains the proposed response. Typically the response is not in the first person, but is written as if coming from the working group. The item is given a label of "Response Only".
The W3C divides its erratum process (covered in 6.2.3. Classes of Changes) between what it terms "editorial" and "substantive". These match very closely to the WCAG errata document, and fairly closely to the labels in the TF when used in combination with the Errata or ErratumRaised labels.
-
Editorial changes are those that involve either "No changes to text content" (fixing broken links, style sheets, or invalid markup) or "Changes that do not functionally affect interpretation of the document" (such as fixing and clarifying non-normative content, and fixing typos and grammatical errors that would not alter someone's interpretation of the requirement).
-
Substantive changes are those that may affect conformance, by making something more or less ambiguous, or altering whether a specific situation is or is not in conformance. (The W3C process also includes the addition or removal of requirements under substantive; however, this is completely out of scope for the TF.)
In addition to this process, it is important to emphasize that the TF contemplates changes in three scenarios:
- Changes to non-normative documents (Understanding, General and Sufficient Techniques)
- Non-normative changes to normative documents ("Introductory material, appendices, sections marked as "non-normative", diagrams, examples, and notes", see 5.1 Interpreting Normative Requirements)
- Normative changes to normative documents
Taking these two concepts together helps understand which changes are listed on the Errata page, and how they become approved and published.
| Errata section | Informative docs | Informative parts of normative docs | Normative parts of normative docs |
|---|---|---|---|
| Editorial | Not listed in errata | Listed in errata | Listed + CFC |
| Substantive | Not listed in errata | Listed + CFC | Listed + CFC |
All changes to the TR specification will be added to the Errata document. Changes to informative documents, such as Understanding and Techniques are not listed in the Errata document.
The incorporation of errata into the TR document is fairly straightforward. Any kind of change to the TR except clear technical gaffs (broken links, broken CSS, broken code) can only be published as part of a date-stamped re-publish. This includes non-normative changes to the TR document. Going forward, the intention is to do an annual republish of the document. Where substantive corrections exist, they may need to go through an additional process
Substantive corrections are ... not to be considered normative until a new Recommendation is published following the process to revise a Recommendation.
Any form of correction for the normative document will be listed in its appropriate category on the errata page as soon as it is approved by the working group (through a CFC for most of these changes). It has not been clarified whether these appear in the editor's draft.
IMPORTANT: The "Substantive" label, when used alone (i.e, without "errata" or "normative") in the task force github process is not intended to equate to Substantive Errata in the errata document, nor what the W3C Process Document describes as "substantive changes". This is because we use the same classification for informative documents. So "Substantive"+ "Understanding" or "Technique" denotes a change that can be implemented as soon as it receives WG approval.
Subject: REVIEW - WCAG 2 proposed changes (due by [DATE])
The following email outlines the updates proposed and implemented by the WCAG 2 Task Force. It provides a two-week window for Working Group members to review non-normative WCAG 2 updates, and consists of changes in several categories.
In addition to the non-normative changes in the sections below, the Task Force has identified a normative change for the Working Group. This is listed here to initiate a normative review process. It will be added to an upcoming call, and if the attending working group members are in general agreement, it will go through a CFC process.
For proposed substantive or editorial changes:
- Give a thumbs up on the pull request description to agree. We are looking for >4 +1 votes (activating the 👍 emoji) for substantive or errata changes
- Or provide feedback in the Conversation to request changes
Based on feedback, those changes will be merged or brought back for another review.
For proposed draft responses to issues, give a thumbs up or comment. If you spot a problem with an implemented bug fix, open a new issue.
Proposed editorial errata changes (changes that do not meaningfully alter informative language in a normative document)
None this cycle.
Proposed substantive changes (changes that meaningfully add or alter existing non-normative guidance)
None this cycle.
None this cycle.
None this cycle.
None this cycle.
- Attend Friday call
- Participate asynchronously in github discussions
- Self-assign issues on the project board
- Subscribe to Listserv: [email protected]
A table showing all merged changes by date
Any member of the TF can triage new or existing issues on github. This entails:
- adding the issue to the project
- deciding if an issue can be closed directly
- deciding if the issue requires task force attention, and if so adding appropriate labels
- adding an initial, potentially generic response
In all cases, our process is to assign the issue to the project, to capture the fact a TF member acted on the issue. So the first step is always:
- Click on the Project gear icon and select "WCAG 2x" (assuming it is not already selected). That will put it in the project as "No status".
There are a number of situations where it may be determined that an issue does not require changes to any documents in order to be resolved.
Some issues are obviously opened by accident, or contain nothing that needs to be acted on. For anything of this nature, choose the dropdown beside the "Close" button and choose "Close as not planned".
Some older issues may have been effectively resolved but not closed.
- Ensure it is labelled with "Response only", where appropriate.
- Choose the "Close" button (the default option is Completed)
-
If an issue has a related PR that has been merged (i.e., the PR is cited in the issue)
- Validate that the PR addresses the issue (and not just part of it)
- Validate that the change has been published on WCAG 2.2
- Click 'Close'
-
If the issue appears to be resolved
- Write a comment such as "This issue is resolved (no longer exists) in WCAG 2.2"
- Click 'Close'
Sometimes it's unclear if the informal responses of participants have fully resolved the issue, either from lack of response by opener/owner, or by the passage of time. If in doubt, we recommend closing with an option for the user to reopen. But if on balance you consider the issue may be unresolved, give the owner a chance to respond.
- If the issue seems addressed, comment: "@[owner], the issue appears to be addressed in the comments, so we are closing this issue. Feel free to reopen and add additional information if you feel this is not resolved."
- If the issue is just stale or the status seems unclear
- "@[owner], is this still an issue? Please provide any update, or close if it is no longer an issue."
- Set label as "Inactive, close soon"
If an issue is a duplicate of another issue, is old and seems to have no point (stale), or will otherwise not be acted on:
- Write a short comment (e.g., "Duplicate of #")
- Choose 'Close as not planned', as in prior case.
Issues that have not had any active conversation may be closed directly. Anyone in the issues thread is welcome to reopen or create a new issue.
In most situations, the issue will need action by the task force.
- Categorize the issue with labels, using the following:
- If it is specific to a success criterion, add that SC's label
- A label can be added for the kind of content (Understanding, Techniques)
At this stage, it is better not to label for the nature of the change (i.e., bug fix, editorial, substantive). This label tends to get added after it has been drafted.
Adding the labels to an issue provides some indication to the issue opener that the issue has been seen. It may also be useful to add a generic response, such as: "Thank you for opening the issue. It has been added to the WCAG 2 TF project, for consideration."
If you do not feel the issue is clear enough, feel free to request clarity from the issue opener.
If the issue seems timely and in your opinion needs action by the working group, you can immediately move it from "No status" to "To do". If you are interested in the issue, you can also assign yourself.