How to review specs and raise issues
The i18n WG uses github to track comments raised against the specs of other WGs. This page outlines how WG members raise those issues. It is verbose to help beginners. Practised hands can just follow the highlighted text for reminders.
Members of the i18n Interest Group are encouraged to submit comments to firstname.lastname@example.org. The i18n WG will then convert those comments to github issues as appropriate. If you are submitting comments to www-international, please submit one comment per email - otherwise the threads are likely to get hopelessly tangled.
You may encounter a new issue while reviewing a spec or come across an issue already raised by someone else in an email thread or bugzilla and feel that the i18n WG should follow that thread. In either case, follow the steps below and click on the links to see detailed instructions.
- Is there a label at https://github.com/w3c/i18n-activity/labels for the document in question?
If yes, go to step 2.
Otherwise, ask @r12a, @aphillips or @fsasaki to create a label, then go to step 2.
- Create an issue.
- Once the i18n WG has reviewed the comments, notify the relevant Working Group.
- Monitor the email/bugzilla thread and contribute to the discussion.
- When the issue has been addressed, add the label to the issue and get agreement from the i18n WG to close it.
i18n WG shepherds are assigned to products to facilitate work on the issues. They bring issues to the i18n WG attention if action is needed to move them forward or close them. In particular, shepherds should regularly check that relevant WGs have been notified about issues raised, but you should check that the i18n WG reviews your new issues.
Labels should be the exact short-name for the document.
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.
Go to https://github.com/w3c/i18n-activity/issues and click on 'New Issue' at the top right of the page.
Add the label for the spec.
If this is an issue you are raising (eg. via a review), follow these steps:
Write a short, succinct title and add the , to signify that this issue needs to be reviewed by the WG. label
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
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.
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.
Otherwise (eg. this is a thread you have noticed and want the WG to track), follow these steps:
Use the subject of the email thread or the bugzilla/github issue as the title and add the , to signify that this issue is being tracked, rather than raised against a WG spec. label
Always start the description with a link to the location of the thread. This is the first email in the email thread, if an email discussion, or to the bugzilla bug or github issue page if that's where the discussion is. For an email discussion, use the thread flattener with the email subject as a parameter, eg.
If the relevant WG uses bugzilla/github:
Create a bug/issue. Add www-international to the cc list for bugzilla bugs. For github, add an i18n tag, if there is one. You'll probably also want to subscribe to notifications for a github issue.
Copy over the information in the issue description to the bugzilla/github description, incorporating any changes that arise out of discussions with the i18n WG.
Edit the issue at w3c/i18n-activity. Replace the initial comment with a link to the bugzilla/github page at the top of the description, such as:
Remove the from the issue. label
If the relevant WG uses email for comments:
- Create an email and copy over the information in the issue description to the body of the email, incorporating any changes that arise out of discussions with the i18n WG.
Send the email to email@example.com 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.)
Edit the issue at w3c/i18n-activity. Replace the initial comment with a link to the email thread flattener at the top of the description along the lines of the following example:
Remove the from the issue. label