ReSpec CANDIDATE CORRECTION wizardry

Hi spec-prod,

First time caller, long time fan... :)

Chris Lilley and I were having a conversation about Process 2021 and the new
"candidate amendments" requirements for Revising a Recommendation. The VCWG is
in "maintenance mode" and is getting ready to publish a revised REC for
Verifiable Credentials v1.1.

As an Editor, I had to manually mark up the substantive changes over the
weekend (we had been merging editorial and candidate changes over the past two
years) and it was not an experience I would wish on anyone.

The process I used was to generate an `htmldiff` between the published REC and
the revised REC, and then hand splice every single substantive change into the
copy that the AC is going to review. What I had done in the past was easy,
just generate a diff for review, but it seems as if the new process requires
you to not include the editorial changes (there were many) and only include
the substantive ones (there were few) in the diff.

The result is explained to the VCWG here:

https://lists.w3.org/Archives/Public/public-vc-wg/2021Oct/0010.html

So, the question revolves around what tooling needs to be provided to spec
Editors, how we can get PRs submitted in a useful form to reduce Editorial
burden, and in general, what the plan is here? My suggestion would be to just
go back to providing a full diff, OR provide a mechanism in ReSpec noting
which sections you want to have diff'd in an exportable revised REC version.

More below...

------------------------------------------------------------
Chris Lilley wrote:

Hi Manu,

On 2021-10-28 16:01, Manu Sporny wrote:
> Hey Chris,
> 
> I'm an Editor on the W3C JSON-LD, Verifiable Credentials, Decentralized 
> Identifiers, etc. specs and we are doing our first substantive updates to
> a Recommendation using the 2021 W3C Process.
> 
> We noticed you had a really nice way of marking candidate corrections in 
> WOFF... perhaps through some ReSpec magic? What we're hoping is that we
> don't have to mark up the candidate corrections manually.

They should not have to be marked up manually, once ReSpec and Bikeshed gain
that capability.

However, the WOFF spec is an older one and does not use either ReSpec or
Bikeshed. So yes, the markup changes were done manually.
https://github.com/w3c/woff/commits/main/woff2/index.html

For the new IFT spec, Fonts WG has moved to Bikeshed. But that spec is still
very early in the WD state so won't need Candidate Additions for some time.

The class names link into the existing /TR stylesheets so the styling happens
correctly. The /TR scripting also adds the change|current|futuretoggle buttons

WebAudio is also doing Rec updates using the 2021 process, and uses Bikeshed:

https://github.com/WebAudio/web-audio-api/commits/main/index.bs

but so far, the updates are being done with manual markup insertion, see for
example
https://github.com/WebAudio/web-audio-api/commit/1ef5e4e8073527d86763ecce4372f1cd260bea4e#diff-5e793325cd2bfc452e268a4aa2f02b4024dd9584bd1db3c2595f61f1ecf7b985

we are using the GitHub issue numbers to generate the candidate correction IDs.

> 
> Is there any tooling available to help markup candidate recommendations in
> the way that you have in WOFF?

Not that I am aware of.

Hacking around with del and ins is a pain, and it is also very easy to end up
with duplicate IDs. Also, the deleted part needs to retain the original ID, to
preserve inbound links, but once it eventually is integrated into the Rec
after AC review, the newly inserted part needs to get those IDs.

It strikes me that this email exchange could help others and maybe we should
be having the conversation on the spec-prod mailing list?

-- 
Chris Lilley
@svgeesus
Technical Director @ W3C
W3C Strategy Team, Core Web Design
W3C Architecture & Technology Team, Core Web & Media

Received on Monday, 1 November 2021 13:29:10 UTC