W3CArchitecture Domain XML

How to use the
issues tracking system for
comments on W3C specifications

Some W3C Working Groups are using Bugzilla to track comments on draft specifications and record the resolutions of those comments. This document explains how to work with the system to make comments on the documents, track their status, and so on.

How do I ... ?

... use Bugzilla? · ... add a comment on the specification? · ... add more detail to an issue raised by someone else? · ... track the status of issues I've raised? · ... know when the Working Group makes a decision on an issue I've raised? · ... let the Working Group know whether I agree with their decision on an issue I've raised? · ... see what issues are currently unresolved? · ... see what issues have been resolved, and how? · ... avoid using Bugzilla? · ... make Bugzilla stop sending me so much mail? · ... learn more about Bugzilla?

... use Bugzilla?

Bugzilla has a Web interface which is quite straightforward. To use the public instance of Bugzilla at W3C (which is where our comment-tracking system is), go to http://www.w3.org/Bugs/Public/.

To search, simply go to the home page and click Search existing bug reports. This will take you to a simple search interface. Then select the name of the specification you want to comment on from the pulldown menu for Product. In some cases the entry in the menu will be not one specification but a cluster of specs: “XML Schema” for part 0, 1, or 2 of the XML Schema specification or for the Schema Component Designators specification, “XPath/XQuery/XSLT” for any of the specificiations related to XSLT 2.0, XQuery 1.0, XPath 2.0, and so on. Having selected the ‘product’, click Search. A so-called ‘advanced search’ is also available; it has a well deserved reputation for having a rather forbidding user interface, but many people report that they have gotten used to it.

To add an issue, or comment on an existing issue, you will need a Bugzilla signon (your email address) and password. Go to the Bugzilla home page and follow the link to Open a new Bugzilla account. You'll be asked for an email address and your real name, and a password will be generated randomly and mailed to your email address. (Among other things, this helps reduce the incidence of spam and of forged applications for accounts.)

Once you have a Bugzilla signon, you'll be able to do all the things described below.

Please bear in mind: although the process of tracking and resolving last-call issues on a technical specification, in order to develop a W3C Recommendation that commands consensus in the community, does have a number of similarities with the process of tracking bugs for purposes of software development (that's why we're using Bugzilla!), the usual terminology is slightly different.

It will perhaps be slightly disorienting to see the tracking system refer to your carefully nuanced question, request for clarification, discussion of a difficult technical issue, editorial suggestion, or other comment on our specifications with the short, blunt term “bug”. If you are making a suggestion to correct a typo, it will certainly be puzzling to be asked which operating system and hardware platform your comment applies to. Please bear with these terminological mismatches.

Rest assured that although Bugzilla may not know the difference between a bug and a request for clarification, we do, and we'll endeavor to treat every comment on our specs appropriately.

... add a comment on the specification?

To comment on any of the specifications for which comments are being tracked in Bugzilla,

  1. Go to the Bugzilla Enter Bug page. If you haven't signed on, so Bugzilla knows who you are, you'll be asked to sign on. If you don't have a signon, you'll need to get one (it's easy) and then sign on.
  2. Select the appropriate ‘product’ for the specification you are interested in (e.g. “XPath/XQuery/XSLT” or “XML Schema”).
  3. Fill in the rest of the form normally.
    • There may be more than one Version for the specification you're commenting on; it's helpful if you specify the correct one. In case of uncertainty, however, you can leave it “unspecified”.
    • Ignore the fields for Platform (irrelevant), and OS (operating system) (irrelevant).
    • Do specify (under Component) which document you're commenting on.
    • If you wish to assign a Priority and Severity to your comment, feel free to do so, but note that the Priority field may be updated by the Working Group member responsible for the issue, as part of the normal management of work flow.
    • Please do not change the Assign To: field; this will be handled by the Working Groups.
    • In the (relatively unlikely) event that there is a Web page which provides a clearer statement of the issue, put its URL in the URL field. Otherwise ignore this field.
    • In the Summary field, write a one-sentence summary of your issue. This may be revised or reformulated by the Working Group member to whom your issue is assigned.
    • In the Description field, describe your issue. Take as much space as you need. It's a good idea to make sure that any information you put in the issue summary is repeated here, in case the summary is later changed by the Working Group. Use normal email-style writing conventions here. If you're tempted to use HTML tagging, resist the temptation — it won't be recognized. (On the plus side, you don't need to escape XML examples in your text.)
    • Ignore the fields for Keywords, Depends on, and Blocks; these may be used by the Working Group for issues management, but you don't need to bother with them.
  4. Click on Commit.

Your Bugzilla signon will be recorded as the reporter of this issue, and you will receive email from Bugzilla whenever the record of the issue is updated. (If you'd like to receive mail for some kinds of update, but not every single one, you can change your email preferences in Bugzilla; there's a link toward the bottom of any Bugzilla page you see after you're signed on.)

... add more detail to an issue raised by someone else?

First, find the issue. Then

  1. Go to the Additional Comments text area. Add your comments.
  2. Click on Commit.

If you are interested in a particular issue, you may wish to add yourself to the CC list for the issue. This will ensure that Bugzilla will send you email whenever the record for the issue is updated.

... track the status of issues I've raised?

When you are logged in to Bugzilla, you will see a link at the foot of the page labeled My Bugs. This will search the Bugzilla database for all bug reports of which you are the originator.

... know when the Working Group makes a decision on an issue I've raised?

There are two ways you can do this.

Under normal circumstances, you will be notified by email whenever the status of your issue report is changed. Actually, you'll be notified by mail whenever anything at all happens to it, either because someone added a comment to it, or the editor of the specification rephrased the summary to include some salient detail, or anything else. You may turn off some kinds of email (see How do I make Bugzilla stop sending me so much mail?, below) if you wish.

Otherwise, if for some reason you don't receive the email notification, you can simply use the built-in search for “My bugs” any time you're signed on to Bugzilla.

Either way, please respond! It's an important part of the W3C development process for Working Groups to get feedback from others, and for this to work right, you need to let the Working Group know whether their response to your comment resolves your concern satisfactorily or not. (See the next question.)

... let the Working Group know whether I agree with their decision on an issue I've raised?

Good question — this is an important part of the process.

When the Working Group reaches a decision on an issue you have raised, you'll be notified by email from Bugzilla.

When you receive that mail, it should include a description of what the WG would like to do to resolve your issue. (In some cases, this may be nothing, if they don't agree with you that there is really a problem.) Please review the proposed resolution carefully, and let the Working Group know whether it's acceptable or not.

If you are satisfied, please go to Bugzilla and add a comment to the issue record saying you've reviewed the resolution and are happy with it. As originator of the issue report, you should also be able to change its status to CLOSED.

Otherwise, please go to Bugzilla and add a comment to the issue record saying you've reviewed the resolution and are not happy with it (and why). If you are not happy with the resolution of the issue, you may if you wish ask that the decision be reviewed by the Director of the W3C when the document leaves Last Call; this is sometimes called ‘appealing to the Director’. Or you may choose to say, in effect, “I won't say I'm happy with your response, but I also don't want to appeal the matter to the Director.” If you want to appeal the question to the Director, you should (a) say so, and (b) change the status of the issue to REOPENED. If you don't want to appeal the decision to the Director, please say that, and change the status of the issue to CLOSED.

If you forget to change the status of the issue, don't worry; the Working Group will update the record in due course, as long as you respond saying clearly whether you are satisfied or not. If you don't respond, the Working Group will assume all is well and after a suitable waiting period will change the status of the issue from RESOLVED to CLOSED.

... see what issues are currently unresolved?

Go to the search screen, and search for open issues against the specification you're interested in. Or just use one of these pre-prepared search links:
XPath / XQuery / XSLT
XML Schema

... see what issues have been resolved, and how?

Go to the search screen, and search for closed issues against the specification you're interested in. Or just use one of these pre-prepared search links:
XML Schema

... make Bugzilla stop sending me so much mail?

Sign on, and click on the Edit: Pref[erences] link. Click the “Email settings” tab. Clear the check boxes that indicate events about which you do not want to be notified by email. Leave checked those boxes which indicate mail you'd like to receive. At the very least, you should leave a checkmark in the box for when “The bug is resolved or verified” in the column for “Reporter”. We are relying on Bugzilla to notify you of the Working Group's decision on how to try to resolve your issues; if you uncheck that box, you won't get that email and we will assume that silence implies consent and that you have no objection to whatever resolution we propose.

... avoid using Bugzilla?

We very much hope you won't want to avoid using Bugzilla. Entering your comments directly into Bugzilla will help us keep our issues list up to date and communicate more effectively with you.

But if you just cannot use Bugzilla to make your comment, you can send comments in email to the appropriate comments list, which should be listed by name in the “Status of This Document” of any W3C specification.. Please note that your comments will be archived and publicly visible.

Comments made in email form will be transferred into the Bugzilla system for tracking and issue management. As part of that process, you may be given a Bugzilla signon (using your email address as the signon ID), and if that is done then Bugzilla will be instructed to send you email whenever the record representing your issue is updated. You don't need to use the signon created for you (i.e. you don't actually need to sign on to Bugzilla if you don't want to). If you do, just go to the Bugzilla login screen, put your email address into the text box after the words “If you have an account, but have forgotten your password, enter your login name below and submit a request to change your password,” and click Submit Request. You'll get email from bugzilla@wiggum.w3.org with your new randomly generated password, which you can then use to sign on, and use Bugzilla as described elsewhere in this document.

If you are not given a Bugzilla password, then the member of the Working Group who transfers your comment into Bugzilla will typically be recorded as the originator of your comment.

... learn more about Bugzilla?

General information on Bugzilla, an open-source bug tracking system, is available at http://www.bugzilla.org/. The standard documentation for the version currently being run on the W3C server is available at http://www.bugzilla.org/docs/2.18/html/index.html.

Maintained by C. M. Sperberg-McQueen for several W3C Working Groups.
$Id: public-bugzilla.html,v 1.3 2006/03/06 03:22:56 ht Exp $