Re: Proposal for Publishing REC Errata

15.10.2014, 18:22, "Stephen Zilles" <szilles@adobe.com>:
>>  -----Original Message-----
>>  From: chaals@yandex-team.ru [mailto:chaals@yandex-team.ru]
>>  This touches on ISSUE-141 (for the tracker)

>>  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.

The Process requires a page, and a link to it. I don't see how that would not be satisfied by a pointer to bugzilla, tracker, a hand-crafted page, or a list of github issues since the Rec publication…

>>  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".

I did not say "nobody wants to do this". What I said is (equivalent in logic to) "without people prepared to do something, making a Process statement that they should do it will not automatically produce the outcome that they 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.

Then get better editors, who can make it clearer what in the document represents 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. Or provide the existing editors with better tools to do the same.

Not useful to whom?

Identifying errata is like identifying changes. Expecting people to read a full "diff" that includes all kinds of irrelevancies is very unhelpful to those who are not tracking the work directly themselves. A list of errata (or changes - it amounts to the same thing) tells someone who periodically checks to see what they should update exactly what they need to look at (if it is moderately well-organised - again something the process doesn't guarantee and that in practise is often not the case). 

>>>  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

In that case, I think the fact that you can't change the Rec "on a whim" is a feature, and I doubt we would get consensus to do things another way.

>>>  --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.

I fail to see how an editor's draft doesn't fulfil this function.

>>>  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).
>>>     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".
>>>  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.

That makes a lot of assumptions about what the Process means by "page". It appears that it means "something you can link to", and it is certainly the case that a Bugzilla query is a webpage, as is an issue list from tracker, etc. I don't see a requirement in the Process that the errata page is on any particular site.

So I suspect we don't need a change just to point to something like an editor's draft (Recommendations should do that anyway, IMHO, unless we truly expect to abandon them on publication) or a buglist.

cheers

Chaals

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

Received on Friday, 17 October 2014 10:43:13 UTC