It is important to track issues for a number of reasons:
- To avoid revisiting work that has already been completed, by having an accurate record to refer to.
- To have a record that can be referred to when requesting a transition of a document, showing which issues were raised and how they were resolved.
- To be able to answer questions about what was accomplished
In a small project, especially one where the decisions are not contentious, it may suffice to track issues informally.
Going forward with XML Security it will be necessary to have a rigorous process where
Issue Content: Issues should be raised in a manner that makes it clear it is a new issue for WG consideration and that is productive, by including an issue justification and proposed resolution. This approach worked well in the WS-Policy working group:
- Title - A short descriptive name for the issue
- Description - A longer and complete description of the issue, state in terms of the documents
- Justification - Why is this an issue? E.g., state an architectural concern, demonstrate an interop problem, explain a use case that isn't met
- Target - What deliverable the issue is against (framework | attachment)
- Proposal - A reasonably complete proposal for how the issue should be addressed.
- It is also appreciated if the proposed solution comes with test cases.
Raising Issues by Mail: Issues can be raised by WG members, by W3C members (e.g. during AC review) or even parties not in W3C. The simplest approach is for parties to raise issues using email, which is natural and convenient, and does not require much setup. To make this workable those raising issues by email must do the following:
Use Subject line of NEW ISSUE: [xyz document] summary
- Provide the content as outlined above, using those headings (e.g. Justification etc)
Ideally there would be a single tool to enter issues, track them and to generate reports. Unfortunately this is not the case. WG members find it easiest to enter issues using email.
Issues List: To make this work we need to actively manage issues, recording them, tracking the status, and sharing that information. To do this we need a consolidated issues list that also can be used to report issues according to document and/or document state (e.g for Draft, Proposed REC etc).
The WG needs to decide on the approach, for example Bugzilla might be appropriate for this.
Issue List Maintainer(s) The WG will need one or more members to act as issue list maintainers. This job is to make sure all issues sent by mail have been recorded into the issues list, and to update the status of items in the issues list as the WG makes progress.
- It is not effective for the chair to attempt to manage the issues list as well as chairing the meeting.
- Independent issues list maintainers will reduce the chance of incomplete or missing issues list.
Report Design We should determine in advance the issue list reports to generate, for example lists of open issues, completed issues, as well as report for transition requests.