How to review specs and raise issues

The i18n WG uses GitHub issues to track review comments raised against the specs of other WGs. This page outlines how to raise issues against a spec, and create other issues in the i18n-activity repository to track those issues. It is verbose to help beginners. Practised hands can just follow the highlighted text for reminders.

The i18n WG also tracks discussions of interest, or discussions brought to their attention by other WGs. This tracking is enabled by applying the i18n-tracker label to an issue in the other WG repo, and creating a tracker issue in the i18n-activity repo. Instructions for handling that are found on another page, under the heading Keeping tracker issues up to date.

Summary

When reviewing a specification for issues related to internationalization, you can use the Short review checklist to get ideas of what to look for.

If you find something that seems to be a problem, follow the steps below. Follow the links for detailed instructions.

  1. Is there a label beginning with s: at https://github.com/w3c/i18n-activity/labels for the document in question?
    If yes, go to step 2.
    Otherwise, ask i18n staff to create a label, then go to step 2.
  2. Create a new issue.
  3. Ask the WG to review any new issues.
  4. Once the i18n WG has reviewed the comments, notify the relevant Working Group.
  5. Monitor and contribute to the discussion thread for the issue(s) raised.
  6. When the issue has been addressed, add the close? label to the issue and get agreement from the i18n WG to close it.

Create a label

If this is the first time a spec with this short-name has been reviewed, you'll need to create a label to identify the spec. You may need a W3C staff person to help do this.

  1. Labels should start with "s:", followed by the exact short-name for the document, with the color #6bc5c6.

  2. Do not include version numbers. For example, use css-text rather than css-text-3 or css3-text. This is because if we use the same label for css3 and css4 and so on, we can spot synergies more easily.

Create a new tracker issue

  1. Go to https://github.com/w3c/i18n-activity/issues/new.

  2. Write a short, succinct title.

  3. Add labels. There should be one label (beginning with s:) to identify the spec, eg. s:annotation-model, or s:css-variables, etc. Also add the pending label, to signify that this issue needs to be reviewed by the WG.

  4. Describe the issue as indicated in the issue template.

    Always start the description with information about the location of the text your comment refers to.  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/2010/WD-WOFF-20101116/#Metadata

    Adding the URI takes a few moments longer, but it saves lots of time later for you and others reading the issue. Where you can, 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.

    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.

  5. Click on Submit new issue.

Ask the WG to review

You should normally allow the i18n WG to comment on any new issues you want to raise, before you send the comment on to the group producing the reviewed spec. The i18n WG should see that you have raised new issues when they receive the daily github digest. However, they will need to be prompted to review the new issues.

Send an agenda+ email several days before a weekly telecon, listing the comments you wish to send on, and asking the WG to consider them.

The telecon will allow for any objections to be aired, and give the go-ahead for comments that are ready to move to the next step.

Notify the relevant WG

These days, all W3C WGs use GitHub for spec development, and you should raise issues in the repository that holds the spec (even if comments direct you to use a mailing list). However, if the group is not using a repo under the w3c organisation you should encourage them to move their repo before sending comments. (Unless, of course, this is a spec from WhatWG, Unicode, etc.)

Here, a 'WG issue' refers to an issue in the repository of the specification being reviewed. A 'tracker issue' refers to an issue raised in the w3c/i18n-activity repository.

The steps are as follows:

  1. Create a new WG issue in the target WG repository.

  2. Add labels to the new WG issue, or ask one of the i18n staff to add them.

    1. Always add an i18n-needs-resolution label.
    2. If you think any of the participants in layout requirements task force groups would be interested in following the discussion, add the appropriate i18n-*lreq label(s).

  3. Add labels to the tracker issue, ie. a needs-resolution label, and any appropriate *lreq label(s). (These are the same labels as used for the WG issue, just without the i18n- prefix.)

    If you added an *lreq label, add the label spec-type-issue and a label to indicate the relevant typographic feature(s), eg. i:line_breaking. The latter represent categories related to the Language Enablement Index, and all start with i:.

    Always add a label starting with t: to indicate the topic, eg. t:text_case. After the t: the label contains an id for a relevant section in the document Internationalization Best Practices for Spec Developers (called 'specdev'). You can attach multiple labels if multiple sections are relevant. These labels automatically establish links between the specdev document and related issues.

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

  5. Edit the tracker issue. Remove the initial comment per the template instructions, leaving just a link to the new github issue at the top of the description.

  6. Remove the pending label from the tracker issue.

Going forward, as long as you are subscribed to the [email protected] mailing list, you will receive a daily digest containing links to all issues that have changed over the past 24 hours. You should track the progress of any issues you raised.