W3C home > Mailing lists > Public > public-apa@w3.org > September 2019

Re: Horizontal review request: the HTML Standard Review Draft

From: Matthew Tylee Atkinson <matkinson@paciellogroup.com>
Date: Wed, 11 Sep 2019 16:38:49 +0100
Cc: Janina Sajka <janina@rednote.net>, Xiaoqian Wu <xiaoqian@w3.org>, lw@tetralogical.com
Message-Id: <CBCD5412-D48A-4311-8F46-B41056798868@paciellogroup.com>
To: W3C WAI Accessible Platform Architectures <public-apa@w3.org>
Hello all,

I've had a quick look into this, how we might get started with identifying the material to review, taking the commit log into consideration, as Léonie suggested. Apologies if any of this is old news, or missing some part of the process. Hope it may be of help...

This URL compares the HTML repo between the date of the last Review Draft and the current one: https://github.com/whatwg/html/compare/master@%7B2019-01-23%7D...master@%7B2019-07-16%7D

In order to produce a human-friendly diff to review, it looks like we'd need to address the following:

1. The HTML Standard's source is in a file called "source" which is an HTML file, but doesn't have the extension, so the diffs on GitHub's site aren't rendered as HTML by default - however it doesn't seem practical to review via GitHub's site as the diffs are large, so really this isn't an issue if we're OK with doing things locally, which seems reasonable.

2. Ideally we'd want to filter out the commits noted as "Editorial: " or "Meta: ", as if we did this, it would streamline the diffs.

3. Also it would be most helpful—possibly vital, even—if we could find out, for any given change, which commit introduced it, as knowing the commit would enable us to link back to any related issues and PRs and thus file any issues in the HTML repo appropriately.

If we were to run things locally from a cloned repo (not via GitHub's site), I expect we could write a script that takes the whole range of commits, filters out the commits we don't need to look at and then generates us an HTML page that contains a pretty version of the changes to the source file. That would address the first two requirements.

In order to address the third, I am currently unsure how to do this, but there are some options, including:

A. Find some existing tool/library that can do this for us. What we want is something like a version of GitHub's so-called "blame" view (which just annotates the diff with commit info). There are several options for where we might look for tooling that already exists.

B. We could do something simpler and, if we write a script to do the filtering, maybe we can modify the diffs as that script percolates, in order to insert a link to the commits on GitHub's site into the text of the source file, so that when we're reviewing the diff, we can immediately visit the relevant commit and any links it offers on GitHub’s site.

Some of the above may require more git-fu than I have (or may already exist) but if you think it'd be of help, I can do more research and exploration of this.

best regards,


Matthew
-- 
Matthew Tylee Atkinson
--
Senior Accessibility Engineer
The Paciello Group
https://www.paciellogroup.com
A Vispero Company
https://www.vispero.com/
--
This message is intended to be confidential and may be legally privileged. It is intended solely for the addressee. If you are not the intended recipient, please delete this message from your system and notify us immediately.
Any disclosure, copying, distribution or action taken or omitted to be taken by an unintended recipient in reliance on this message is prohibited and may be unlawful.
Received on Wednesday, 11 September 2019 15:39:13 UTC

This archive was generated by hypermail 2.4.0 : Thursday, 24 March 2022 20:23:06 UTC