Re: Proposal for Publishing REC Errata

On 2014-10-15 09:34, Jeff Jaffe wrote:
>
> On 10/15/2014 12:22 PM, Stephen Zilles wrote:
>>
>>> -----Original Message-----
>>> From: chaals@yandex-team.ru [mailto:chaals@yandex-team.ru]
>>> Sent: Wednesday, October 15, 2014 8:11 AM
>>> To: fantasai; W3C Process Community Group
>>> Subject: Re: Proposal for Publishing REC Errata
>>>
>>> This touches on ISSUE-141 (for the tracker)
>> [SZ] Yes, this proposal came out of the discussion is ISSUE-141 in 
>> the 14 October Process TF Telcon. It was in response to ACTION-35.
>>> There is a related issue (that I will raise some time) that groups 
>>> are generally
>>> chartered with the usually ridiculous assumption that they will be 
>>> closed in a
>>> few years - maybe about one year after the 18 months it took to 
>>> create a
>>> Recommendation… but that issue is a different one.
>>>
>>> 15.10.2014, 04:33, "fantasai" <fantasai.lists@inkedblade.net>:
>>>> Background
>>>> ----------
>>>>
>>>> The Process TF discussed errata today. There was a motion to clarify
>>>>     a) That errata can include substantive changes, but not new 
>>>> features.
>>>>     b) That errata should be maintained frequently, at least 
>>>> quarterly.
>>>>
>>>> The problem with merely trying to enforce more frequent updates of
>>>> errata is that the errata-management mandated by the Process is
>>>> onerous for editors and WGs.
>>> I don't understand that, since the Process says "you have to track 
>>> them" and
>>> doesn't mandate how.
>> [SZ] Actually, it does say that you "must track errata on an "errata 
>> page." An errata page is a list of enumerated errors, possibly 
>> accompanied by corrections. Each Recommendation links to an errata 
>> page; see the Team's Publication Rules." That is why this proposal 
>> was put forward.
>>> I suggest we keep the "how" out of the Process.
>> [SZ] I believe there was some level of agreement in the discussion on 
>> the Telcon, but there ought to be some accepted conventions for how 
>> errata are presented to insure that readers can reliably find them. I 
>> am not sure whether those conventions should be part of the Process 
>> or Best Practices.
>>> I believe the immediate problem is that telling Working Groups they 
>>> have to
>>> do something nobody in the group wants to do doesn't ensure that it 
>>> will
>>> happen. (There are various underlying causes for this occurring… we
>>> probably see the full range in W3C)
>> [SZ] I would disagree with "nobody wants to do". As far as I can tell 
>> most WG members would prefer to have one very public document that 
>> reflects consensus agreement on the specification. The complaint 
>> being addressed by ISSUE-141 is that too often that is only the 
>> Editor's Draft and that does not always reflect consensus. The CSS WG 
>> would like to update it prior specs (earlier versions) when errata 
>> are discovered, but find that the "errata page" is not a very useful 
>> way to accomplish these updates.
>
> Re: "nobody wants to do"
>
> I think there is an education piece.  In the past, Errata might have 
> been viewed as a bother - something that nobody wants to do. What we 
> have learned from the WHATWG community is that the community very much 
> wants to have a document that keeps up to date and corrects errors.  
> Perhaps if it is called errata noone wants to do it - but if it is 
> called "an updated corrected spec" might will want to do it.
>
> It suggests that we should have an education piece to this as well; 
> first educating the Chairs and then the WGs.
>
>>>> Problem
>>>> -------
>>>>
>>>> One of the major problems with errata is that they are maintained as a
>>>> separate document, independent of the text of the actual 
>>>> specification.
>>>> This is a severe usability problem, as persons using the spec are
>>>> expected to apply the diffs as they read.
>>>>
>>>> The current approach also means that an editor's draft which
>>>> incorporates the changes cannot be published until the tests and
>>>> passing implementations are available
>>> On what basis? Editor's drafts can be whatever the working group 
>>> agrees,
>>> and can be published whenever the Working Group agrees - in both cases
>>> this agreement is *typically* of the form "we delegate this decision 
>>> to an
>>> editor".
>> [SZ] What was not clear in Elika's statement is that she is talking 
>> about updating a REC which requires Process Step, 7.7.2 Revising a 
>> Recommendation, similar to the PR-REC transition. That transition 
>> requires an implementation report to show the changes are 
>> implementable (and, ideally, implementated). That is what Elika is 
>> referring to, not updating the Editor's Draft
>>>> --which can take months or even years after an erratum is resolved by
>>>> the WG. The CSS2.1 spec, for example, has not been kept up-to-date on
>>>> /TR because of these requirements: the editor's draft accepts changes,
>>>> but we cannot republish because not all of those changes have
>>>> corresponding tests and passing implementations yet.
>>> Do you mean you cannot republish the editor's draft as a REC unless 
>>> you go
>>> through the Edited Rec steps? IMHO that's a feature, although I 
>>> understand
>>> that it has costs.
>> [SZ] There was no consideration (at the Telcon) of not using the 
>> Revising a Recommendation step. What is being requested is a way of 
>> idenfying provisional revisions as soon as they are reasonably 
>> "baked", but not necessarily fully implemented and tested. The reason 
>> for this is you want a specification that the potential implementers 
>> can use for the implementation.

So this means only for substantive changes that are not new features?  
If it was editorial changes, it doesn't need tests.  If it's substantive 
and a new feature, it gets published in a new WD.

Couldn't the CSS WG create a new WD or WG Note for a new version, CSS2.2 
(or "CSS2.1 provisional with errata") and include changes they agree on 
that are substantive but not a new feature in that? (and put no new 
features in that).  That would be a document where people can see the WG 
consensus of their proposal for an updated CSS 2.1 spec in one place. It 
could clearly state at the top that it was a WD with no status and it 
collected the changes they want to eventually put into an Edited CSS 2.1 
REC, but could change.  It could link to a version that shows diffs from 
CSS 2.1.  As content has implementations and test, it could be rolled 
into the CSS 2.1 Edited Recommendation.

That doesn't require a process change.  The Errata document could link 
to it. (or a link could be added to the header material of CSS 2.1).


>>>> Proposal
>>>> --------
>>>>
>>>> The proposal to resolve this problem is to keep the errata inline in
>>>> the official REC publication. Two options make sense to me:
>>>>
>>>>     A. Write in the errata as diff marks (using <ins> and <del>) in 
>>>> the
>>>>        spec. Maintain a separate list similar to a DoC explaining
>>>>        the changes, and possibly also tracking the status of their
>>>> tests
>>>>        and impls.
>>> This might fly, but it strikes me as an annoying way to have to read 
>>> a spec,
>>> for everyone (those who want the latest version and those who don't).

why do it in the spec, why not in a separate WG Note (maybe with a link 
in the REC)? (with careful wording that says the errata are not in the 
REC itself because the vetting process for them has not completed and 
they could change).  there would need to be a separate errata page, 
because the diff isn't that.  it isn't a list of what the errata were 
and why there was a problem.

>>>
>>>>     B. Fold in the errata completely into the spec text. Maintain a
>>>>        separate list of changes including the exact diffs from the
>>>>        validated REC text.
>>> I'd be surprised if this gets consensus, as it has teh same problem 
>>> we already
>>> have. It just moves it from people involved with the spec to the 
>>> "silent
>>> users".

If the reason it isn't in an Edited REC is that it's waiting for 
implementation and test, it isn't clear it really is what is wanted in 
the REC, so why put it in the REC?  Why not in another document?

The idea of a REC is that it is a snapshot that has stability, consensus 
and good evidence that it works and can be implemented interoperably 
(implementations, tests).  If it can show that, it should be able to be 
published.

A WG could have stricter rules than the Process may require, but that 
would be up to the WG.

>>>
>>>> Example
>>>> -------
>>>>
>>>> An example of approach B can be seen in the recent Flexbox LC:
>>>> http://www.w3.org/TR/2014/WD-css-flexbox-1-20140925/#changes
>>>> The changes since the previous CR have been folded into the main text,
>>>> but we have maintained a list distilling all non-trivial changes to
>>>> help implementations understand the differences and be sure to update
>>>> their implementations to match the changes.
>>>> Where a section has gone through multiple revisions to resolve an
>>>> issue, these are folded down to a single set of diffs between the
>>>> dated (snapshotted) drafts, minimizing the noise in the changes list.
>>>>
>>>> The corresponding example of A would be for the diffs to be written
>>>> directly into the main text rather than tracked in the Changes list.
>>>> (There would then be no up-to-date text, only change-marked text.)
>>>>
>>>> Related Concerns
>>>> ----------------
>>>>
>>>> There's a separate question of how proposed corrections get ratified
>>>> as official REC text. I'll post separately on this.
>>>>
>>>> Also, theoretically the errata page lists all known errors, not just
>>>> those with proposed corrections. Since most groups track issues using
>>>> some method other than an errata page on www.w3.org, that requirement
>>>> is probably best handled as a link to the appropriate issues list.
>>> Yep. There's no reason not to do so, and no change required to the 
>>> process.
>> [SZ] Given the current statement in 7.7.1 about using an "errata 
>> page" it would seem that a change to the Process is necessary.

 From the process: "An errata page is a list of enumerated errors, 
possibly accompanied by corrections."  It reflects WG consensus.  We 
shouldn't change that.

An issues list is typically anything someone thinks is a problem, 
without any consensus (until it's settled).  We can't have people having 
to wade through an issues list to figure out what the errata are.  But 
if some WG decided to have a moderated issues list that only contained a 
clear description of the errata and it's resolution by the WG (not the 
entire history of all discussion of it) that sounds like an "errata 
page" as defined in the Process document.

It has to be a clear list of problems the WG agrees are problems and 
resolutions the WG agrees with.  And then it should move into the REC as 
soon as possible.

I think having a WG Note that shows what it would look like if it turns 
out OK to do could help motivate people to do the parts that need to be 
done - like convince the Director it can be implemented compatibly.

Frequent publications of Edited RECs for the easy cases would be good.


>>> cheers
>>>
>>> -- 
>>> Charles McCathie Nevile - web standards - CTO Office, Yandex
>>> chaals@yandex-team.ru - - - Find more at http://yandex.com
>
>
>

Received on Wednesday, 15 October 2014 21:21:43 UTC