Raise-a-review-request
This is a PROPOSAL for a way of raising a review request using GitHub rather than email.
Rationale
Email is free-form, so we may miss some information. It also requires us to manually transfer the request to GitHub so that we can integrate it with our Review Radar. The current process can lead to requests being lost on their journey to the radar (happened with TTML2), but also involves an unnecessary amount of manual copy/pasting. Raising directly in GitHub can reduce these issues.
When email is sent to www-international, it is potentially seen by around 300 subscribers, but we can still get this benefit by automating notifications from GitHub to www-international.
Current plans
The i18n WG has discussed this and, unless we hear objections (esp. from PLH), we would like to create a new GH repository and move our radar there. Then set up a template for new requests, and direct people to ask us for reviews by raising a GH issue.
We believe that having a new repo will help, in particular, with identifying and routing notifications, but it will also declutter the i18n-activity repo too.
Proposed process
The requester creates a new issue at https://github.com/w3c/i18n-activity/issues/ and fills in information described in our guide page at https://www.w3.org/International/review-request.
It would be better if there was a template provided automatically in the comment field when an issue is created. However, in the i18n-activity repo we already use the standard template for issue tracking. There may be an way to create an alternative template? Alternatively, we could move the radar to a new, dedicated repository? PLH may also be preparing some alternative, form-based mechanism for WGs to request HR, which would gather information and create an issue in our repository?
Typical information required includes:
- name of spec to be reviewed
- URL of spec
- pointer to an explainer for the spec
- next steps for this document in the Rec/Note track
- when the next transition is expected
- when would the WG like a reply from i18n WG
- information about what has changed since a previous review
- information arising from any preliminary evaluation by the WG
- where (and possibly how) to file issues arising
- other comments
Many of these items may be expressed in multiple sentences, paragraphs and lists.
It would typically be useful for Working groups to raise one GH issue per document to be reviewed.
Each time one of these isssues is raised, we should send a notification to www-international so that it can be picked up by i18n WG participants, labelled correctly, and added to the review radar. Since people from other WGs are not likely to be able to apply labels such as REVIEW REQUESTED, it would be hard to identify these issues separately from other normal review issues at the point when they are raised. This would be different if we had a dedicated repo for such requests; in that case we could automatically send them out with a dedicated notification, and point them to various alternative email addresses.
Labelling. This would be done by i18n WG personnel.
- An incoming request would normally have a REVIEW REQUESTED label, to distinguish it from other less urgent review opportunities in the radar.
- A variety of labels are used to indicate whether the document is headed for FPWD, CR, etc.
- a Pending label should be attached until the group has discussed the request and assigned a reviewer.
I18n personnel should bring new requests into the Project Radar, currently at https://github.com/w3c/i18n-activity/projects/1 using the standardised card notation: Spec name with link > date due.
New requests should be discussed during the weekly telecon, and someone assigned to review.