-
Notifications
You must be signed in to change notification settings - Fork 23
Process overview for reviews and tracking
WG-repo-issue: An issue raised in the repo of a WG that is developing a spec or document.
i18n-tracker-issue: An issue raised in the i18n-activity repo by the i18n WG to track a given WG-repo-issue or lreq-issue.
lreq-issue: An issue raised in a repository owned by a language enablement group (such as alreq, the Arabic Layout Requirements task force). Generally speaking, the i18n WG is only interested in issues of this type if the contain a question about how a language or script works.
spec-WG: The Working Group developing a specification.
i18n-WG: The internationalisation Working Group.
Every WG owned repository in the W3C GitHub organization that represents a spec or document in development, and several in the WhatWG organization, have the labels i18n-needs-resolution and i18n-tracker.
Here is how they are used:
- i18n-tracker: The Internationalization (i18n) Group may add this label to indicate that they are following a discussion. Other WGs can also add the label to any issue to automatically bring the discussion to the attention of the i18n Group. Issues with this label don't need to be resolved to the satisfaction of the i18n Group before a transition.
- i18n-needs-resolution: The Internationalization (i18n) Group has raised, or is following this issue, and expects it to be resolved to their satisfaction before a transition. This label is added/applied only by the i18n Group, and should only be removed by them. It may replace an i18n-tracker label.
In addition, the i18n-WG adds ‘lreq’ labels to WG-repo-issues if they feel that a particular Language Enablement group needs to be aware of the discussion. These labels have the general shape i18n-xlreq, where x can be a for the Arabic layout task force, afr for African layout task force, and so on. If these labels are applied to an issue, the relevant group will be notified of changes to the issue in their daily digest notifications.
If WGs create repositories using PLH’s template tool, the -tracker and -needs-resolution labels should be automatically added to new labels. Otherwise, it’s necessary to periodically check https://www.w3.org/2019/10/gh-labels.html?search=i18n for repos without the labels, and add the labels to those.
In addition to the aforementioned labels, various other labels are used to manage the issues through the review and discussion involved in horizontal tracking of issues. There are also labels used to automate pages such as the following:
Instructions for use of these labels are included in the pages linked to below.
This describes the process that the i18n WG uses for raising issues during review, and tracking those and other issues.
Detailed instructions for reviewing specs and raising issues can be found in the page How to review specs and raise issues . What follows is just a summary:
- the reviewer looks for issues in the spec by reading it, and uses the short and long checklists as reminders/guides.
- when an issue is found, they go to https://github.com/w3c/i18n-activity/issues/new/choose and use the “Add a review comment (pending discussion by i18n WG)” template to create a provisional comment. They apply a ‘pending’ label to show that this requires review by the i18n WG. This issue is not yet seen by the spec-WG.
- they advise the i18n-WG that they’d like to send the comment on, giving time for the i18n-WG to review the comments prior to a telecon, and the i18n-WG gives advice during the telecon.
- if a comment is blessed by the i18n-WG, the reviewer raises an issue in the repo of the spec-WG, and converts the provisional comment in the i18n-activity repo to a tracker issue. The tracker issue will be used to monitor progress on the comment made on the spec. Discussion on the tracker issue is restricted to meta information about the progress of the WG-repo-issue; all discussion of the comment itself should occur in the repo of the appropriate WG. The issue in the WG repo will have an
i18n-needs-resolutionlabel, which indicates that the i18n WG wants to be satisfied with the resolution before a transition occurs. - the i18n-tracker-issue remains open until the i18n-WG is satisfied with the response from the spec-WG, regardless of whether the WG-repo-issue is closed by the spec-WG. When the spec-WG closes their issue, or an i18n-WG participant thinks that the comment is addressed, a
Close?label is attached to the i18n-tracker-issue, to indicate to the i18n-WG that they should consider whether the tracker should be closed. (Future tooling should apply that label automatically if the target WG closes the comment.) - once the i18n-WG is satisfied with the resolution of the WG-repo-issue, they close the i18n-tracker-issue.
- prior to a transition, the director or stand-in will check whether there are open i18n-tracker-issues in the i18n-activity repo for the spec in question. If there are, they will try to ascertain the outstanding issue(s) with the spec. Therefore, it would make sense for the WG going to transition to check with the i18n WG whether there are outstanding issues.
Labels can be attached to i18n-tracker-issues to raise their priority for discussion by the i18n-WG. These include:
-
needs-attention: Indicates that the i18n-WG should look more urgently at an issue. After setting this label, a request should be sent out to the i18n-WG to review this issue prior to an upcoming teleconference. (Note that the telecon should be the place we decide what to do about an issue, not the place we first start reading about it.) -
advice-requested: Indicates that the spec-WG has explicitly asked the i18n-WG to contribute to a discussion. This also raises the urgency with which the i18n-WG will deal with this issue.
When tracker issues are closed, they can be given a recycle label beforehand in cases where the issue wasn’t resolved and the intent is to resurrect them when work begins on a new version of the spec.
The spec-WG may want the i18n WG to pay attention to an issue raised in their repo. They do this by adding the i18n-tracker label to the issue.
I18n-WG participants may also set the i18n-tracker label on issues that catch their eye, so that the i18n-WG can follow developments.
Tooling then automatically notifies the i18n-WG of this issue in their daily digests, and creates an i18n-tracker-issue in the i18n-activity repo with a pending label. I18n personnel then apply any additional labels needed for the tracker issue, and remove the pending label. (Detailed instructions are found in Keeping tracker issues up to date
.)
If the i18n WG considers that an issue brought to its attention in this way merits it, they may change the label from i18n-tracker to i18n-needs-resolution, indicating that they wish to see a mutually agreeable resolution to this issue before a transition occurs.
The needs-attention and advice-requested labels can be attached to the tracker issue to raise their visibility for the i18n WG, if needed.
The i18n WG tracks questions posed to ‘lreq’ groups, so that those questions can be reflected in the Language enablement tracker and the Language Enablement Index.
Detailed instructions for setting up related tracker issues are found in Keeping tracker issues up to date .
We don't yet have a tool to automatically create tracker issues for new lreq issues that have the question label added to them. That has to be done manually.
The i18n-WG has several channels in place to notify people about changes in discussion threads. I'll try to list those here.
Notifications are set up by editing https://github.com/w3c/github-notify-ml-config/blob/master/mls.json.
'Review comments' sent daily to [email protected]
The main notification channel for tracking discussion with spec-WGs, this notification reports movement on issues with the i18n-needs-resolution and i18n-tracker labels only, thanks to the eventfilter setting. (A few other labels are mentioned, but they should now be obsolete.) It doesn't report any movement on issue lists in i18n repos.
The rules set includes the line "repoList": "https://w3c.github.io/validate-repos/hr-repos.json", which should pull notifications from all GitHub repos in the W3C domain where specs and documents are being produced by WGs. This tool was developed by Dominique Hazael-Massieux and PLH.
There are additional entries for WhatWG repos: "repos": ["whatwg/encoding", "whatwg/html", "whatwg/url"],.
'Review comments' sent weekly to [email protected]
This gathers together the notifications mentioned just above for a whole week, and is sent out late afternoon UTC on a Wednesday (to allow people to recap before the telecon on Thursday).
'Tracker items' sent weekly to [email protected]
This reports on changes to issues in the i18n-activity repo (ie. the tracker issues) for a whole week, and is also sent out late afternoon UTC on a Wednesday (to allow people to recap before the telecon on Thursday).
We may need to add to this notification a list of tracker issues that have received the Close? label, although it's easy enough to find those by going to the review tracker page. (Though not just the ones that were given that label over the past week.)
'Lreq' tracking
The script at https://github.com/w3c/github-notify-ml-config/blob/master/mls.json contains several notification rules that alert participants in layout task forces about changes to issues in their own repository. The i18n-...lreq labels applied to various spec-WG issues also cause changes to issues in those repositories to be reported to the group. For example, if a CSS issue has the i18n-alreq label, changes to that issue will be notified daily to the alreq group.
We currently don't have a way of notifying the i18n-WG about issues that have been given a question label in the lreq repositories over the past week.