RE: Proposal for managing GitHub issues & comments

Unless expectations have changed recently, at later stages of the W3C Process, the working group will be required to address every open issue (including every individual public comment) formally - that is, with a decision and a written response.

We need an approach to issue tracking that can handle a potentially high volume of individual comments made about working drafts, while maintaining a searchable record of the issues raised, responses given, and the working group's decisions. The only way to make this tractable is with an issue tracking tool. It used to be Bugzilla; now it's GitHub; I haven't yet heard or read any proposal for an alternative that would meet the above requirements. It is also unrealistic to expect that working group participants will have significant time to invest in managing aspects of issue tracking that can and should be automated.

Sooner or later, I suspect, we will need to maintain a "one comment plus follow-up discussion per issue" expectation, rather than a "one SC proposal per issue" expectation as we currently have it.

I trust these matters will be kept in mind by the Chairs and Staff Contact in addressing the working group's issue tracking needs.

From: Repsher, Stephen J [mailto:stephen.j.repsher@boeing.com]
Sent: Tuesday, March 14, 2017 4:56 PM
To: WCAG <w3c-wai-gl@w3.org>
Subject: Proposal for managing GitHub issues & comments

I'd like to propose a paradigm shift in the way the group is currently managing GitHub issues.  My aim is to increase momentum of productive discussion and resolution.  I do not claim that this is a solution to tool usage problems for certain disabilities or personal preference, but hope members agree it is a calculated step in the right direction.

Michael's proposal addresses a few very key issues, but the problems stemming from a long thread of comments on one GitHub issue per SC remain.  There are many months of discussion left as everyone knows, so these problems are going to get much worse by sticking to this restriction.  I propose we shed it, and allow issues to be raised for each distinct concern related to the current repository, which is fundamentally how most issue trackers are setup to function.  Some advantages are:

  *   Shorter, more focused comment threads hopefully much easier to read
  *   Sub-issues much less likely to be missed or not addressed
  *   "Easy" issues can be quickly resolved and closed, leaving the WG and task force calls to focus on the list of current feedback
  *   Reviewers do not waste time reading historical comments already addressed in the current SC version (since these should be in a closed issue)
  *   Number (and type) of open issues per SC provides a simple readiness metric

Issue management can then be handled using labels and milestones:

  1.  Create labels for each SC short name, and assign to issues accordingly.  This allows anyone to easily see the distinct issues that have been raised regarding a particular criterion, and which are open or closed.  Links can be provided in the wiki table to these custom searches.  It also allows better tracking of issues that may affect multiple criteria, e.g. a common glossary definition, since multiple labels can be applied to one issue.
  2.  Create 3-4 labels to indicate the category of a raised issue, such as:

     *   Editorial: Spelling, grammar, glossary links, general structure, or anything else that does not raise an issue with the SC concept (these should be able to be addressed quickly and online only so as to not waste call time)
     *   Conflict: Issue raised is related to conflict, overlap, or redundancy with another existing or proposed SC
     *   Implementation: Issue raises questions about implementation, e.g. technology independence, too restrictive, etc.
     *   Testability: Issue specifically relates to problems with the testing method

  1.  Consider also using milestones related to our 2.1 release timetable.  The difficult topic of how to assign issues to milestones I'll leave to the chairs (you're welcome), but this would certainly help reviewers prioritize where they spend their time.

Write access to a repo is needed to manage labels so it is important to increase the number of people with sufficient permissions, otherwise still many issues may go unaddressed.  These same users would also need to make sure to pay attention to closing and merging duplicate issues as with any other large open source projects.

Of course, the major disadvantage of such an approach is the risk of high volume and bloat, but in my opinion the advantages outweigh this risk.
If the group decides to take this or a similar route, We might ask that users troll their existing GitHub and/or survey comments for criteria in the FPWD, and create new issues for each distinct problem to be addressed, taking care not to duplicate.  Appropriate labels can be applied and then the original SC issue closed and future workflow revolves around the new issues.

Thoughts?

Steve


________________________________

This e-mail and any files transmitted with it may contain privileged or confidential information. It is solely for use by the individual for whom it is intended, even if addressed incorrectly. If you received this e-mail in error, please notify the sender; do not disclose, copy, distribute, or take any action in reliance on the contents of this information; and delete it from your system. Any other use of this e-mail is prohibited.


Thank you for your compliance.

________________________________