Re: ReSpec CANDIDATE CORRECTION wizardry

> On 8 Nov 2021, at 11:40 am, Manu Sporny <msporny@digitalbazaar.com> wrote:
> 
> 
> My biggest concern is that I don't know how to get Editors out of the critical
> path for marking up candidate corrections/candidate additions/proposed
> corrections/proposed additions.

I'm not sure what you mean by the above (particularly "out of the critical path"). Could you help me understand that a bit more?  

> During Verifiable Credentials v1.1, the WG members provided multiple proposed
> corrections. None of us knew at the time that we needed to mark these up in
> any special way, and so two years of these built up.

Ah! Ok, yes. The Working Group, the Chair, the Team, and the Editors need to be *super organized* and make sure they are keeping really good GIT hygiene. 

Consider the commit history for Payment Request or Geolocation: 
https://github.com/w3c/payment-request/commits/gh-pages
https://github.com/w3c/geolocation-api/commits/gh-pages

You notice how we label things "Editorial:", "Chore:", etc.? That allows us to filter out non-essential commit messages, and identify any that are substantive changes:
https://www.w3.org/TR/payment-request/#changelog

The change log is generated automatically using <rs-changelog>.


> Luckily, that only
> resulted in like 3 proposed corrections... but one of them was a change from
> RFC3339 datetime to XMLSCHEMA11-2 datetime, which rippled throughout the
> entire spec. Again, that wasn't /that/ bad... but woe to the WG that needs to
> search/replace a normative dependency throughout the specification.

Yes. Got it. That's why using commit history/change log and links to pull requests is better... looking at diffs is probably going to break down at that point.  

> We did end up marking all of those PRs with "substantive" github labels, so
> perhaps Editors just need to be put on notice that any block-level element
> that contains changes needs to be expanded to contain the old text and the new
> text?

Maybe... that's exactly what we need to figure out. That seems pretty annoying tho.  

> If that's done, then ReSpec can generate the diff between the old text
> and the new text... and once the corrections are out, the Editors have to go
> back through the document and delete all the old text?

Or, maybe we just provide a link to Github so people can just view the diff there?... it provides a better view of the changes.

> Feels error prone... to the point where it might just be better to do a full
> diff of the file.

Agree. This is way overkill to the point of getting silly... we need something better here.  

> I get that people want to get fancy, but the burden on the
> Editors is high and the possibility of error (when doing the cleanup) is
> pretty high as well.
> 
> I'll put these thoughts in the issue.

That be great. I feel your pain/frustration though... we need to do better here. 

The WHATWG snapshots don't seem to need all this silliness and that seems to be putting the W3C at a disadvantage. 

 Hopefully we reduce this down to a simple list of changes and a couple of purple boxes.

Received on Monday, 8 November 2021 01:33:05 UTC