W3C

 

On this page

How to raise issues in the i18n Tracker

The i18n WG uses tracker to track comments raised against the specs of other WGs. This page outlines how to raise those issues.

Warning: Be careful about using the back button with tracker, since it often does the same thing again, including creating duplicate issues. Always follow links. (I usually edit an issue in a separate window, which I can then close down when i want to return to the list of issues, etc.)

Read this stuff about product types first

All comments should be raised as an issue against a product in the tracker database. This is basically a tag which is used for grouping comments. We use the following types of product tags:

  1. .prep products. When an issue is first created, it is assigned to a .prep- product. The comment is only visible internally at this point. The name of the product is usually the short name for a spec, prepended by .prep- (eg. .prep-contacts-api). You can raise issues in these products at any time. A member of the i18n WG assigned to 'shepherd' that product will push these issues out to the target Working Group.

  2. 'live' review products. These products are dedicated to comments arising from review of a particular spec, but their names have no prefixes. For example, the live product for the Contacts API spec is just called contacts-api. These products contain issues that have been communicated to another working group.

  3. .monitor products. These products are typically named after technologies or working groups, and have the prefix .monitor-. You would normally raise an issue in one of these products if you come across a discussion related to internationalization on a mailing list or in a bugzilla database, rather than while reviewing a spec, that you think may be of interest to the i18n WG. In some cases the i18n WG may want to take up the issue and send comments to the WG concerned, in which case the issue would be moved to a .adhoc product (see below).

  4. .adhoc products. These products are similar to the .monitor products, except that the i18n WG has become involved in the discussion. Moving an issue to, or creating an issue in, a .monitor product helps us see more easily which issues need to be tracked carefully to resolution.

High level view, by task

A number of different tasks are listed below, each with a set of steps to follow. At various points, follow the links for more detailed steps.

Raising issues while reading a spec

  1. Check at http://www.w3.org/International/track/products whether there is a product in the tracker that refers to the document for which you are raising issues and that has a name that begins with .prep-. For example, if you are raising issues for the HTML5 specification, you should look for the product .prep-html5. If there isn't one, see how to create a .prep- product.
  2. Read the spec being reviewed and take notes.
  3. Go through your notes and identify a list of comments, trying to ensure that each comment addresses a single issue only.
  4. For each comment, raise an issue in the tracker under the .prep-xxx product (where xxx is the short name of the spec). To create an issue, just go to http://www.w3.org/International/track/ and click on 'Create' under 'Issues' at the top right of the page. Then follow the steps for writing up the issue details.
  5. Each time you create an issue, an email is sent to the public-i18n-core list to notify the WG. Other members of the WG can comment on the issue at that point, and controversial or significant issues may be brought up at the weekly WG telecon.

Sending issues to another Working Group

  1. Each .prep product should have a 'shepherd' assigned to ensure that the issues are moved on, in a timely manner, to the Working Group that wrote the spec. When there are issues to be forwarded, the shepherd will send a note to the WG pointing to a list of issues that need to be moved on. This note should be sent a minimum of 3 days before a WG telecon, to allow people time to review the issues, and should specify the date at which the shepherd plans to send the issues to the other WG. The date should be some time following the next teleconference.
  2. Working Group members should review the comments and raise objections in email or on the telecon agenda.
  3. When the date specified by the shepherd arrives, the shepherd either closes the issues or, if non-controversial, moves it to the 'live' product, ie. the one used to track comments actually sent to the spec WG. (If a live product doesn't exist, they should follow the steps to create one.)
  4. What the shepherd does depends on whether the Working Group who wrote the spec wants comments in email or in a bugzilla database. See how to send comments by email. See how to send comments to a bugzilla database.

After a comment has been sent to a Working Group

  1. For WGs that use email lists, discuss the comment by email in the normal way. Always ensure that the i18n-ISSUE-xx is present, and that both the i18n mailing list and the target WG are in the email address.
  2. For WGs that use bugzilla, hold the discussion in the bug itself. Bugzilla will notify the i18n list each time a change is made to the bug.

You have found an email thread or bugzilla bug that the WG should track.

  1. Check at http://www.w3.org/International/track/products whether there is a product in the tracker that refers to the technology for which you are raising issues and that has a name that begins with .monitor-. For example, for issues related to HTML you should look for the product .monitor-html. If there isn't one, create a .monitor- product.
  2. Raise an issue in the tracker under the .monitor-xxx product (where xxx is the short name of the spec). To create an issue, just go to http://www.w3.org/International/track/ and click on 'Create' under 'Issues' at the top right of the page. Then write up the issue details.
  3. Each time you create an issue, an email is sent to the public-i18n-core list to notify the WG. You could then get the Working Group's backing for your comment by either discussion on the mailing list or bringing to the weekly WG telecon.
  4. After this discussion you will typically either close the issue, or move it to the a tracker product with an .adhoc- prefix (if the WG wants to participate in the public discussion).

Creating a product

  1. Click on the Add a new product link at the bottom of the list of products.

  2. Choose a name for the product that represents the document concisely (the short form of a document name used in it's URI is usually a good idea). Use the appropriate prefix for the product name. Type the name in the Name field

  3. If this is a product with a name prefix, leave the mailing list selection set to default (public-i18n-core@w3.org).

  4. Otherwise, to make this a 'live' review product, you will need to select a mailing list as follows:
    1. If the spec you are reviewing specifies an email list to which they want you to send comments, you will need to ensure that the issue you raise will go to that list as well as the appropriate i18n list. You should click on the radio button Custom mailing list(s) and add BOTH the most relevant i18n list, and the mailing list specified by the other WG for spec comments.
    2. If the group works with a bugzilla database (eg. HTML5) you WON'T need to add the other Working Group's email address to the notification list, since the discussion should take place in bugzilla. Just leave the radio button set to the default mailing list.
    3. If the community that would deal with this spec uses an i18n mailing list such as public-i18n-bidi or public-i18n-cjk, etc., you could use the custom field to associate that mailing list with this product, in addition to public-i18n-core. We'll refer to that mailing list or public-i18n-core in the rest of these instructions as the 'i18n mailing list'.

Writing up issue details for review comments

  1. Write a short, succinct title. (Ignore the Nickname field in tracker.)

  2. Choose the product (this will be the .prep-xxx tracker product we mentioned earlier).

  3. Fill in Raised by

  4. Always start the description with information about the location of the text your comment refers to unless the comment is not about a specific part of the spec.  Do this by listing the section number and name, followed by a URI.  For example:

    6.2.1 Extended Metadata Block
    http://www.w3.org/TR/WOFF/#Metadata

    Try to always use dated versions of the spec and point to the section in that dated version. This makes it easier to see the original text later. Adding the URI takes a few moments longer, but it saves lots of time later for you and others reading the issue.

  5. Then write your comment, in as succinct and well-organised a way as possible.  It is usually helpful to quote the text you are commenting on at the beginning of your comment. For example,

    "The text elements MAY be given a lang attribute."
    We feel that you should use xml:lang for this.
  6. Click on Create.

Writing up issue details for monitored discussions

  1. Use the title of the email or bugzilla bug for the title of the issue you are raising. (Ignore the Nickname field in tracker.)

  2. Choose the product (this will normally be a .monitor-xxx tracker product).

  3. Fill in Raised by with your name, or the name of the person who owns this issue.

  4. Always start the description with a link to the first email in the email thread, if an email discussion, or to the bugzilla bug, if a bugzilla-based discussion.

    Thread: <link>, or

    Bugzilla: <link>

  5. Add the name of the person who created the thread or bug, eg.

    Raised by: Anne Other

  6. If there is no link to the appropriate section of the specification being discussed, you could add one. Make the link specific to the appropriate section, where possible, eg.

    About: <link to spec section>

  7. Now copy the content of the first email in the thread or the first entry in the bugzilla bug stream to the description field. This usually summarises the initial issue and makes it easier to remember what the issue is about.

  8. Click on Create.

Moving an issue to a 'live' review product for bugzilla-based comment systems

  1. To create a bug, log in using the email address of the i18n list where you want emails to be copied (usually www-international) (ask Richard Ishida for help with the password).

  2. IMPORTANT Start the bugzilla summary field with "i18n-" and add the title of the tracker comment - leading to a summary such as "i18n-ISSUE-72: BOM as preferred encoding declaration". This is important, because it means that the tracker will track the emails that are sent to public-i18n-core, and it will not confuse this issue with issues of the other WG.

  3. Copy over the information in the tracker issue description to the bugzilla description, incorporating any changes that arise out of discussions with the i18n WG.

  4. Add a very short note about the provenance of the comment, eg. something like one of the following:
    1. (Personal comment not discussed by i18n WG.)
    2. (Personal comment based on discussion with i18n WG.)
    3. (Sent on behalf of the i18n WG after discussion.)
  5. Click on Save Changes.

  6. Go back to the tracker, and change the product of the issue to the 'live' version, ie. the product name without the .prep- prefix.

  7. Edit the description field of the issue, adding a link to the bugzilla bug at the top.

Moving an issue to a 'live' review product for email-based comment systems

  1. Change the issue's 'product' association to the 'live' version, ie. the product name without the .prep- prefix.

  2. Click on Save Changes.

  3. Create an email and copy over the information in the tracker issue description to the body of the email, incorporating any changes that arise out of discussions with the i18n WG.
  4. IMPORTANT Start the email subject field with "i18n-" and add the title of the tracker comment - leading to a summary such as "i18n-ISSUE-72: BOM as preferred encoding declaration". This is important, because it means that the tracker will track the emails that are sent to public-i18n-core, and it will not confuse this issue with issues of the other WG.

  5. Add a very short note about the provenance of the comment, eg. something like one of the following:
    1. (Personal comment not discussed by i18n WG.)
    2. (Personal comment based on discussion with i18n WG.)
    3. (Sent on behalf of the i18n WG after discussion.)
  6. Send the email to www-international@w3.org and to the WG that produced the specification. (Note that we are not sending to public-i18n-core.) If appropriate, the email could be sent to one of the other IG lists instead of or in addition to www-international.)


Copyright © 2013 W3C ® (MIT, ERCIM, Keio, Beihang) Usage policies apply.
Content last changed 2013-01-23 19:43 GMT.