Member → The Art of Consensus →

bugs2html - Generating Disposition of Comments out of Bugzilla

This Guidebook is the collected wisdom of the W3C Group Chairs and other collaborators.

Purpose

bugs2html is an XSLT 2.0 stylesheet bugs2html.xsl and a separate set of entities bugs2html-specinfo.dtd for generating a simple disposition of comments out of Bugzilla. The output provides just enough information for a transition call, but not more. The benefit is that the process is mostly automated, and it takes not much time to set it up.

Before Using bugs2html: Preparing Bugzilla

NOTE: You need appropriate access rights to Bugzilla for the following steps. Talk to your W3C staff contact or me for more information.

• Go to http://www.w3.org/Bugs/Public/editproducts.cgi and click on Add a product.
• Enter at least the name of the product and a description. Press the Add button. Your product will now be listed at http://www.w3.org/Bugs/Public/editproducts.cgi.
• At that page, click on your product in the Edit product... column. You will be directed to a page like http://www.w3.org/Bugs/Public/editproducts.cgi?action=edit&product=myProduct.
• At that page, click on Edit components and on the following page Add a new component ... (and repeat these steps for each deliverable you want to track via Bugzilla.). Enter the name of the component (normally one of the deliverables your WG is working on), the description and the default assignee (e.g. the mail address of the WG chair or staff contact). The default QA contact is optional and can be set e.g. to a mailing list you want to use for notification of new bugs and bug changes.
  Note that you cannot enter more than one user ID (which is normally the mail address of a user) in these fields. Note also that these users normally get mail notifications for all bug changes related to a component (that can be a lot of mail ...). It depends on the user preferences what changes they will be notified for. The preferences can be changed at http://www.w3.org/Bugs/Public/userprefs.cgi?tab=email.
• To be able to find Bugs related to a specific review period (e.g. Last Call), you should add versions to your product. You can do that starting at e.g. http://www.w3.org/Bugs/Public/editversions.cgi?product=myProduct by clicking on Edit versions.
• You might also consider to set milestones for your products, also starting at http://www.w3.org/Bugs/Public/editproducts.cgi?action=edit&product=myProduct and clicking on Edit milestones.

Simple Usage

1. Make a query for the bugs you want to integrate into the disposition of comments. Press the "XML" export button.
2. The exported XML is not well-formed and not valid against the Bugzilla DTD - due to a Bugzilla Bug :(. To make it well-formed, delete the XML-declaration and the DOCTYPE from the XML document. You can see a sample XML document here.
3. Download bugs2html.xsl and bugs2html-specinfo.dtd.
4. In bugs2html-specinfo.dtd, adapt the following entities:
   • specTitle (the title of your specification)
   • specPubDate (the publication date)
   • specStatus (the status (e.g. Working Draft for a transition WD>CR, or Candidate Recommendation for a transition CR>PR))
   • specLink (a link to the latest published version of your specification)
   • wg (the name of the working group)
5. Run the XML document against bugs2html.xsl. You can see a sample output here. NOTE: if you don't have an XSLT 2.0 processor available, you might consider using the public W3C Online XSLT 2.0 Service.

Why (and how) does it work + Advanced Usage

bugs2html assumes the following usage of Bugzilla:

• Bugs marked with the resolution FIXED: The Working Group has accepted the comment and the reviewer is satisfied.
• Bugs marked with the resolution WONTFIX: The Working Group has not accepted the comment and the reviewer is satisfied.

In addition to these two categories, there are four categories which don't rely on the Bugzilla "resolution" field:

• externalComments: the comment was made by somebody who is not a participant of the working group.
• resolutionsWithoutResponse: there is no resonse from the reviewer to the resolution of the working group.
• reviewerNotSatisfied: the reviewer is not satisfied.
• nonEditorialChange: the change made in response to the issue is non-editorial (i.e. a possibly substantive change).

There are two ways to use these four categories:

• Use within Bugzilla the keywords externalComment, noResponse, reviewerNotSatisfied or nonEditorialChange.
• In bugs2html-specinfo.dtd, add in the necessary entity (externalComment, resolutionsWithoutResponse, reviewerNotSatisfied or nonEditorialChange) a comma-separated list of the bug IDs relevant to the category.

The latter method is faster than changing the bugzilla entries themselves.

If Everything fails ...

... you have probably used other fields than "resolution" in Bugzilla to express the relevant categories. In that case, you can adapt the XPath expressions used by bugs2html to fulfill your needs: they are encapsulated in the entities (see bugs2html-specinfo.dtd) wgAcceptsCommentXPath, wgRejectsCommentXPath, reviewerSatisfiedXPath, reviewerNotSatisfiedXPath, noResponseXPath, nonEditorialChangeXPath and externalCommentsXPath.