Jump to content

Horizontal Review

From Accessible Platform Architectures Working Group

NOTE: This page is being developed, to document the revised APA horizontal review process. If you are requesting or carrying out reviews, please use your existing process for now!

Requesting Horizontal Review from APA

For Specifications

TBD

For GitHub issues

TBD

Carrying out Horizontal Review (APA participants)

For Specifications

Thank you for helping to review a spec!

There are a few repositories that are of importance here:

  • a11y-request: is where we receive review requests for a specific version of a spec.
  • a11y-tracking: is where we draft issues (or questions) we think need to be raised on the spec. Multiple issues may arise from one spec review - we should keep each issue we raise to one specific question or concern. This repo also helps us follow progress on issues we raised in other repos, and issues in other repos that were flagged as relevant to accessibility.
  • a11y-longitudinal-tracking: is where we record the results of all the spec reviews we do over time - so we can refer to how a spec has changed across versions.

    Historically, such longitudinal tracking was done via this wiki, but we're embracing the GitHub-based horizontal review process, so have moved this function to a GitHub repo. Issues (corresponding to specs) in the longitudinal tracking repo link back to wiki pages, where relevant.

When you review a spec, and find issues/concerns/questions about it, you'll need to file a draft comment (i.e. GitHub issue) in APA space for each issue/concern/question you found. We'll then review this together and, when we have consensus, you can transfer your issue to the source group's repo for them to process.

If you find you do not think there are any issues on a spec, you can feed that back via the APA mailing list or on the call.

When you've filed all of the issues on which we have consensus, you can add a single comment to APA's longitudinal tracking issue for the spec, which links to all the issues you filed, so we can keep track of the outputs of each review. (Instructions on doing this part TBA.)

We've copied this process from the excellent documentation provided by the Internationalization WG.

Create a new tracker issue

  1. Go to https://github.com/w3c/a11y-tracking/issues/new?template=add-a-review-comment--pending-discussion-by-apa-wg.md
  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.
  5. 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

  1. 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.
  2. 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.

  1. Click on Submit new issue.

Ask the APA WG to review

You should normally allow the APA WG to comment on any new issues you want to raise, before you send the comment on to the group producing the reviewed spec.

Ensure that your newly-filed draft comment issue is labelled agenda+ so that we notice it when building the agenda for the APA call. If you file the comment less than 2 days prior to the APA call, please email group-apa-chairs@w3.org to let us know that you've added the comment, and we'll add it to the agenda.

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 (and WHATWG) use GitHub for spec development, and you should raise issues in the repository that holds the spec.

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/a11y-tracking 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 APA WG staff to add them.
    1. Always add an a11y-needs-resolution label.
  3. Add labels to the tracker issue, i.e. a needs-resolution label. (These are the same labels as used for the WG issue, just without the "a11y-" prefix.)
  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 APA 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.


For GitHub Issues

TBD

Tracking Horizontal Reviews

For APA participants

You can track all of your assigned GitHub issues on the web: https://github.com/issues/assigned

Also, the review actions that are assigned to you can be found on the dashboard at: https://github.com/orgs/w3c/projects/155/views/4

For APA chairs and staff

TODO

  • Spec review dashboard
  • Issue review
  • Charter review dashboard

Reference & Acknowledgements

TODO: ACK Team and i18's work and docs.

Retrieved from "https://www.w3.org/WAI/APA/wiki/index.php?title=Horizontal_Review&oldid=4477"