Do we really want manual proposed corrections? (was: Re: Proposed Correction extension for ReSpec?)

Marcos thanks for the quick and detailed response, breaking your concerns out
into a separate thread because I share the concerns and we may want to fold
them back into a "Do we really want this process?" question to go back to the
Process CG.

On 11/21/21 7:18 PM, Marcos Caceres wrote:
>> 1. Do others think that's the sort of thing we are looking for?
> 
> This is good, but I'm still extremely concerned about the amount of manual 
> labour being dumped on spec Editors.

Same, I worry about the newer Editors and the training the Staff is going to
need to do when shifting into "maintenance mode".

> <rant> In particular, I feel pretty strongly that Editors shouldn't be put 
> in a position where they have to manually include before/after changes.
> I'm hearing _a lot_ of negative feedback from folks in multiple working
> groups about how annoying/frustrating this process is going to be, which is
> really concerning to me as and editor, tool maintainer, staff, and as a
> chair.

Yes, it turns what are fairly simple specification PRs into an involved
affair. In the WGs I'm involved with, it would result in the Editors rejecting
just about every candidate change PR by well-meaning authors and re-authoring
it themselves to do the fancy markup that's required (even if we had a ReSpec
plugin to make it easy). I have no idea how we automate this via the Github API.

Now, don't get me wrong -- even the amount of pain the VCWG went through this
time is totally worth it in order to signal to the market that "yes, we are
maintaining the spec, and yes we can make substantive changes if we absolutely
have to." <-- customers love this for a variety of reasons:

* It signals that they picked an open standard that is
  being actively maintained and staves off spec rot
  for a few years.

* They know that bugs are going to be fixed in a timely
  manner and that there is a process for doing so.

* They know that there is also, simultaneously, stability
  and the WG isn't going to come in and change the whole
  thing around.

So, if Process 2021 required the Editors to juggle flaming knives while riding
a unicycle and chanting "candidate corrections are not proposed corrections,
proposed corrections are not proposed additions, proposed additions are not
candidate corrections, <repeat>"... we would do that, because the benefits
outweigh the drawbacks.

That said, unicycling, juggling, and fire control are three skills that have
eluded me throughout most of my life, so I'd rather just have a simpler
process than what I expect will happen if we do nothing. :P

> If it proves too much, most Editors will opt to just stay in CR or just
> opt to publish as REC and then go straight back to FPWD (or, I'll be 
> recommending they do this instead to save them the trouble). That seems 
> counter productive and defeats the purpose of what we were trying to 
> achieve with the Process changes. </rant>

So, let's fix this so it's not as painful as what we expect it to be.

The simplest fix that I can think of is changing to this mode of operation:

1. The changelog in the specification lists "editorial
   changes" and "substantive" changes since the last
   release, like we do here:

https://www.w3.org/TR/vc-data-model/#revision-history

2. You either link manually to the PRs for substantive
   changes, or we upgrade rs-changelog to make that easier
   for folks.

3. We get rid of all the proposed correction markup
   and point AC Reviewers to the Changelog at the bottom
   of each spec (which has links to the PRs if they really
   want to dig in).

4. We provide a diff-marked version as a part of the
   review.

If we do those things, and IIUC, we don't disrupt the regular Github workflow
that most WGs are using. We just require "editorial" or "substantive" labels
on PRs done when revising a REC (which we already require when generating the
new errata.html pages).

I've raised this as a Process CG issue here:

https://github.com/w3c/w3process/issues/589

Thoughts?

-- manu

-- 
Manu Sporny - https://www.linkedin.com/in/manusporny/
Founder/CEO - Digital Bazaar, Inc.
News: Digital Bazaar Announces New Case Studies (2021)
https://www.digitalbazaar.com/

Received on Monday, 22 November 2021 16:04:47 UTC