Automation requirements

Requirements for automation of the tool chain used for notification and tracking of WG issues by the i18n WG.

These requirements are described in terms of the i18n WG’s needs, but it’s likely that they are relevant to other horizontal groups.

1. Automatic assignment of i18n labels to new (and old) repos

Any new W3C repo should automatically have i18n-tracker and i18n-needs-resolution labels (preferably using our preferred mauve background). This will standardise usage and allow WGs to use the i18n-tracker label straight away.

While setting this up for new repos, we should ensure that all exist repos in use also have those labels.

I18n also uses some i18n-*lreq labels, but it will probably be better not to automatically add those. They can be added as needed by i18n staff. This is because there are a largish number of such tags, and they are typically only needed for a small number of repos.

Current status: i18n-needs-resolution and i18n-tracker labels have been added to all WG & IG repos under the W3C organisation. Other variants (such as HR:i18n-comment) have been converted to the standard i18n-needs-resolution or i18n-tracker names.

We have not done the same for CGs. We may do this in the future (at least for the i18n-tracker label), depending on how things develop. We also excluded all i18n repos.

We standardised on the colour #F9C9FF for the background of labels.

New repositories only have the labels set up automatically if the person sets up the repo using PLH's repo template. Otherwise, we need to periodically run the tool to check for repos without labels, and PLH can be asked to propogate the labels to repos that need them.

2. Notification of changes to WG issues we are tracking

It should not be necessary to manually set up notifications by editing the page at https://github.com/w3c/github-notify-ml-config/blob/master/mls.json for repos in the W3C domain. All repos should notify the i18n group of progress on any issue as soon as someone adds a i18n-specific label to the issue.

• Currently, the subject line of notification emails contains “Review comments:”, which is good to keep.
• The current evenFilter is set as follows: "eventFilter": { "label": ["i18n","i18n-comment","i18n-tracking","HR:i18n-comment","HR:i18n-tracking","i18n-review", "i18n-needs-resolution", "i18n-tracker"]. The event filter looks for a variety of labels, due to WGs adding their own in the past. We would like to standardise on the i18n-tracker and i18n-needs-resolution labels.
• These notifications are sent daily to www-international.
• The same notifications are also sent weekly to public-i18n-core on a Wednesday (the day before the telecon).
• We’d want to be able to adjust notification topics and dates, if we wanted to.
• We probably don't want the list of repos searched to appear at the bottom of the notification email, since this would be very long and not much use.
• The whatwg/html and whatwg/encoding repos (and potentially more) should also send notifications.

Here is the meaning of the two labels:

• i18n-needs-resolution: The i18n WG 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 WG, and should only be removed by them. It may replace an i18n-tracker label.

• i18n-tracker: The i18n WG 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 WG. Issues with this label don't need to be resolved to the satisfaction of the i18n WG before a transition.

Current status: This is now running.

The list of repos searched has been inserted into an HTML details element, which means that it is only shown if the user wants to see it.

"whatwg/encoding", "whatwg/html", and "whatwg/url" repos are included in the notifications, because they were left in the rules set at https://github.com/w3c/github-notify-ml-config/blob/master/mls.json

3. Automatic creation of tracker issues for WG issues being tracked

This is relevant for WG issues to which the i18n-tracker label is applied. It isn’t relevant for WG issues to which an i18n-needs-resolution label is applied, since those are generally created manually by the i18n WG from an exisiting tracker issue.

The current manual process for this can be found at https://www.w3.org/International/wiki/Keeping_tracker_issues_up_to_date.

• When an i18n-tracking label is added to a WG issue for the first time, in any WG repo, a tracker issue should be created in the i18n-activity repo’s issue list, if one doesn't already exist.
• The tracker issue should have the same format as, for example, https://github.com/w3c/i18n-activity/issues/754
  • the title should be the same as that of the WG issue
  • The first comment should start with the paragraph: “This is a tracker issue. Only discuss …”
  • There should be a link back to the WG issue in a separate paragraph, of which the first character must be §. Eg. “§ w3c/csswg-drafts#4171” (This line is used by other applications.)
  • Add the ‘tracker’ label.
  • Add a ‘pending’ label: This will signal to the i18n group that they need to do a couple of manual things: (a) add a document/spec label, (b) add an advice-requested label if that is the case, (c) add a yellow label for typographic feature, if appropriate
• If the WG-issue has any labels of the pattern i18n-*lreq, the corresponding labels should be assigned to the tracker issue. The corresponding issues are currently the same, but without the ‘i18n-‘ prefix. Also, a ‘spec-type-issue’ label should be added to the tracker issue.
• Any time i18n-*lreq labels are added to or removed from the WG-issue this should be reflected in the i18n tracker issue.

For WG issues that are created after i18n reviews by the i18n WG, in which case we normally attach an i18n-needs-resolution label, this wouldn't create a tracker issue automatically. This is by design. Such issues usually start in the i18n tracker repo, and after review an issue is raised manually in the WG's repository. The tracker issue persists after this.

In the rare case where an exisiting WG issue is found to be important enough to get an i18n-needs-resolution label straight away, the tracker issue creation wouldn't be triggered. For those cases, it is expected that we would apply both i18n-needs-resolution and i18n-tracker labels together (and then probably remove the latter at a later date).

Current status: This is now working, but requires a daily manual intervention by PLH.

The new tracker issue has a spec name label applied to it automatically if such a label exists in the tracker repo. There may be occasions where this label is not automatically applied, and i18n staff will need to add it.

4. Automatic tracking of closure of WG-issues

• If a WG-issue being tracked is closed, the label “close?” should be automatically added to the tracker issue.
• If the WG-issue is reopened, the “close?” label should probably not change.

To make this kind of thing easier (and comparison of lreq labels), it probably makes sense to store a list of tracker issues and their corresponding WG-issues somewhere on the server, with information about lreq labels and open/close status, so that comparisons can be made quickly.

Note that it should be possible to detect whether an item had the Close? label attached automatically or manually by looking at who applied it. If GH tells us that PLH did it, it is likely to be automatically applied.

Current status: Awaiting implementation.

5. Automatic creation of tracker issues for lreq issues with the Question label

This is similar to the requirements above for WG-issues, but the trigger comes from a specific (but editable) set of repositories and is only applied when an issue in one of those repositories has the label Question applied. Examples of the tracker issues for this type of item can be seen at https://github.com/w3c/i18n-activity/labels/type-info-request.

(These issues are tracked in the layout tracker page at http://w3c.github.io/i18n-activity/textlayout/ and allow us to view what questions are currently outstanding for a variety of scripts and typographic features.)

• The tracker issue should have the same format as that described above, in terms of the title and first comment.
• The label type-info-request should be added, and an appropriate *lreq label.
• The yellow label indicated the typographic feature will need to be added manually.
• Add a pending label to indicate that this is new and the typographic label needs to be added.

Current status: Awaiting implementation.

6. Automatically add tracker issue for review requests

This is likely to take additional thought and longer to implement.

The basic idea is that WGs could request a review using a tool that requests relevant information, such as URL of the spec, date when the review needs to be finished, contact name, GH repo for comments, etc.

Then the software would raise an issue automatically in the i18n-activity or some other repo in sucha a way that it can automatically be added to the project page at https://github.com/w3c/i18n-activity/projects/1 or similar (the review radar).

Current status: Awaiting implementation.

However, we now have a series of templates in place for raising new issues in the (new) i18n-request repo, which removes much of the need for this.