HTML Review Draft and CR has no list of changes

[nigelmegitt]

It is effectively impossible to review the review draft of HTML because it does not link to changes since the previous version.

I hoped to see a list of changes, or a link to one, at https://html.spec.whatwg.org/review-drafts/2020-01/#w3c-rec however it is absent from there. I understand that:

• the MOU with WHATWG omits any requirement for a list of changes in the draft publication format document, and that
• the Process does not require the list of changes,

but for non-WHATWG specs, where pubrules apply, pubrules does require a changelist, for good reason.

Why can't I review without the changelist?

A Process-required feature of a CR is that it contains exit criteria. As per the MOU, implementation reporting is done on a per-feature level with data in the "margin" (quotes because there is no margin when I look at it). The per-feature labelling of implementation does not consistently reference any tests, but does sometimes reference, say, caniuse.

Since this is a snapshot including a bunch of changes since the last snapshot, it makes sense that all those changes should have associated implementation reports, and it is in line with normal W3C practice to establish those implementations by means of tests. The MOU suggests that there should be tests in wpt.

Therefore I should be able to traverse the document, find the new or changed features, and see the tests and implementations for each of them.

This is not possible because the new or changed features are not distinguishable from the very large set of pre-existing features.

It is possible to look outside the document and find the list of changes, for example at #8, but I only know that because someone told me.

What would a workable solution be?

Since it is possible to create the list of changes, perhaps that list could be used as the basis for a changelist document and we could propose to WHATWG that we publish that document and they include a link to it in the snapshot W3C Recommendation section?

I don't know how much additional work it would be for the changelist document to link to the specific changed sections in the snapshot itself, but that would make traversal and review possible by a human, which is at least a nice-to-have, I'm thinking.

[LJWatson]

I may be wrong but I believe the MoU forbids us from making any changes other than indicating which features are at risk based on W3C implementation experience. It is possible we cannot add a link to associated materials, even something like a changelog. It might be worth opening an issue on the WHATWG HTML repo to ask about having a changelog being added at source? It is likely that the lawyers for whom the review drafts were originally put in place would find it helpful too, and it would be a more simple process if it could be done this way.

[nigelmegitt]

@LJWatson Thanks, that's potentially an important point. It is unclear to me if the MoU forbids any change. I see in 5.8:

Be published in a mutually agreed style, as shown in Appendix 1;

and Appendix 1 is titled "Sample Jointly Published Document".

Those together suggest to me that if we make a request and WHATWG agrees to it, then by definition that is a change to the mutually agreed style.

It is not clear to me what the permitted scope of divergence is between the appendix 1 sample and any actual published documents.

I raised this query here first to see if other members agree it would be a good idea, before opening an issue on the WHATWG HTML repo. I think if there is consensus here then raising that issue would be the next action to take.

[LJWatson]

I do find changelogs very useful myself, and I know when HTML was part of WebPlat we had a lot of feedback from reviewers to say they found the changelog in HTML5.1 and 5.2 useful.

[nigelmegitt]

Thanks @LJWatson I'll leave this a few days and then if there are no dissenting voices I'll take it up with WHATWG.

All further support welcome!