RE: errata again, responding to the november proposal

Comments in line below
Steve Z

From: Wayne Carr [mailto:wayne.carr@linux.intel.com]
Sent: Monday, January 19, 2015 2:22 PM
To: Stephen Zilles; Revising W3C Process Community Group
Subject: Re: errata again, responding to the november proposal

I think there are too many different things mixed into this and it would be better to have a section just on corrections to an existing Recommendations, so new features wouldn't be part of it at all - just corrections.
[SZ] I am a bit confused. The point of the last sentence in 7.7.2 is that New Features are not part of this section. What made you think they were?


7.7.2 could be renamed "Correcting a Recommendation without creating a new version"

Editorial changes, class 1 and 2, where there are no changes to implementations should be updated frequently directly in the REC.  And as Stephen suggested, it could revert to not require a PR.  Either the WG or W3C staff should be able to do that.  Having known glaring errors in the spec for long periods of time shouldn't be addressed by having to consult some other errata document.

Editorial changes (1 and 2) could be called Edited Recommendations.  A correction that could change implementations (substantive changes to correct text on existing features) could be called Revised Recommendations. And anything more than that would be a regular REC and not discussed in that section other than to say anything else requires a new version starting from FPWD.

Preparation for publishing a Revised Recommendation could use a "Revised Working Draft" that include the unapproved substantive corrections showing the changes from the REC.  RECS could point to one of those along with pointing to an errata list.  It would not be a REC itself, just a draft being used for a future Revised REC.  I think that may address the use case Jeff has been concerned about.

Separate topic - current Process seems to have an error in this section: " Proposed Edited Recommendation" seems to mean class 1 and 2 in the current process.  "Edited Recommendation" seems to include class 3 substantive changes as well and I'm not sure what else. ("In the latter two cases ..." - not clear what that refers to though substantive changes that are not a new feature is right before it so seems likely to be included)
[SZ] I think I understand why you raise this separate topic. The intent was that CR for an Edited REC would next go to Proposed Edited REC to complete an AC Review. However, the text does not make this clear as you note. The changes you suggest would revert the, I believe, unintentional change for classes 1 and 2 and would allow us to add a PER step for class 3.



On 2015-01-19 13:27, Stephen Zilles wrote:

Top posting to summarize several separate threads

There seem to be several separate issues intertwined in this thread:

1.      The original issue of Issue-141 which was encouraging Working Groups to be more responsive in updating errata to RECs. There seems to be little disagreement that this is desirable, but there seems to be some concern that additional requirements will lead to better performance.

2.      The issue of whether RECs can be “updated in place”. This issue arose because, in the original discussion of Errata Management, some of the commenters (and, in particular, Fantasai) noted that people (whether users or developers or implementors) were going to the REC and getting out of date information. The goal of these commenters was to attempt to insure that people accessing RECs would be aware that there might be more current information which, although not yet normative, was better than that in the REC. Some people have argued that RECs should stay as they are and that such updated information should be in a separate document which itself might take a number of forms, ranging from an auto-generated errata/issues/bugs list to a draft of the REC which has the Errata text in situ.  There seems to be little disagreement that a separate document can be used. The disagreement seems to be whether the REC document can, itself, have better indications as to what the errata are and what changes are proposed to correct the errata. The November proposal allowed the REC to be updated in place provided that a reader could recover, say by a style sheet change or some other mechanism, the original text of the Normative REC or by another stylesheet could view text which reflects some level of errata processing (prior to publishing an Edited Recommendation). The current commenters seem to believe that this would be a bad thing for the W3C to do although in practice this may be little different from having a separate draft with the errata.

3.      The next issue seems to be whether it is necessary (as the current Process provides) to handle Errata separately from New Features. There are, currently, two key distinctions in the Process that distinguish the way a Working Group handles changes that are currently classed as Errata versus New Features. The first is that changes that correct Errata can be made Normative by making a CR for an Edited Recommendation, which triggers a call for exclusions on any new content and an AC review, but New Features must follow the full process of advancing a technical report to Recommendation beginning with a new First Public Working Draft. The second is that New Features may require a charter revision (and approval by the AC.)

If no new features are planned, then the Errata Management Process is simpler and makes sense. If, however, New Features are planned, then having a separate processes for Errata and New Features makes less sense. Having two processes seems to imply having two separate documents, one with the Errata changes and the other with both the Errata changes and the New Feature changes. This seems to imply a duplication of work, although New Features may make some of the Errata changes be different than they would otherwise be.

Another piece of the story is that New Feature Working Document may progress much more slowly (due to implementation uptake) than do Errata changes (which are often aimed at improving interoperability and have quicker uptake). Getting these agreed and implemented changes into a Normative status as quickly as feasible is one justification for using separate processes (with some duplication) for Errata and New Features.

There seem to be two separate sub-issues: (a) should we have two processes, one for REC track work in general and one (simpler one) for Errata and (b) should it be possible to handle Errata processing using the general REC track process? If we do have two separate processes, then it is important to have a definition of what Errata are. If we chose to use the REC track process for Errata, then such a definition is not important.



These three “issues” are relatively independent. The first issue is much simpler than the latter two. It seems tractable to handle in Process 2015. The other two issues seem to be more contentious and seem less likely (at this point in time) to be settled by Process 2015. I suggest we open separate tracking Issues on the last two of the above “issues” and that will allow us to proceed on them independently.



I can live with David Singer’s proposed minimal modifications to the November proposal to get something that responds to Issue-141 into Process 2015 even though it does not allow my preferred solution to Issue 2. above.



Steve Z



> -----Original Message-----

> From: David Singer [mailto:singer@apple.com]

> Sent: Friday, January 16, 2015 11:39 AM

> To: chaals@yandex-team.ru<mailto:chaals@yandex-team.ru>

> Cc: Jeff Jaffe; Revising W3C Process Community Group

> Subject: Re: errata again, responding to the november proposal

>

>

> > On Jan 15, 2015, at 12:02 , chaals@yandex-team.ru<mailto:chaals@yandex-team.ru> wrote:

> >

> >

> >

> > 15.01.2015, 22:46, "David Singer" <singer@apple.com<mailto:singer@apple.com>>:

> >>>  On Jan 14, 2015, at 17:52 , Jeff Jaffe <jeff@w3.org<mailto:jeff@w3.org>> wrote:

> >>>

> >>>  On 1/14/2015 4:23 PM, David Singer wrote:

> >>>>  Hi

> >>>>

> >>>>  my issues with the proposed text:

> >>>>

> >>>>  a) it is NOT ‘the recommendation’ but a document using the

> Recommendation as a basis, if inline reporting and editing are done.

> >>>>  b) This assumes only one way of working — editing in-place.  I think the

> old model is workable (manual errata page) and a model with a list of errata

> auto-generated from a database (e.g. issues, bugzilla) is also workable.

> >>>>  c) I have no idea who ‘interested parties’ are for the must requirement in

> the last paragraph, so I don’t know how it’s testable. In fact, what is this

> paragraph trying to say or do?

> >>>>

> >>>>  So, here are my ‘minimal' changes.

> >>>  Your concerns are well stated and also similar to Chaals'.

> >>>

> >>>  I responded with suggestions to Chaals' thread, in a way that is somewhat

> similar to your (although I think your writing and flow is better than mine).

> >>>

> >>>  One item that I emphasized in my version is that the document that bases

> on REC text and clearly identifies proposed corrections should be identified as a

> best practice.  Wdyt about that?

> >>

> >> Thanks

> >>

> >> I tried in my text not to suggest that this document that is based on a

> recommendation text could only contain errata and fixes; it’s fine if it also

> contains improvements, I think. The reader just needs to know what is what.

> >>

> >> Chaals, do you want to make this more explicit?  I define errata as classes 1-

> 3, but don’t say that any document is restricted only to errata.

> >

> > I don't want to define errata separately from other bugs or improvements. I

> don't want to treat them differently, either.

>

> I think errata are a normative part of the process, and this section is about

> errata management.  Saying you have to keep track of bugs that are reported

> that the WG agrees are errors in the spec. is errata management. So I disagree

> on your first point; errata need definition in a section that is about them.

>

> Your second point — nothing in this section either mandates specific handling

> (we only go so far as saying a new document is a best practice) nor forbids

> using those mechanisms for other purposes (perhaps we need to clarify and

> change “errata page” to “a page which lists the errata”). So I agree, if your

> integrated document lists not only errata but new features, that’s fine by me.

>

> >

> >> The last paragraph still bugs me. Is this just saying that if X

> >> reports “Y is a bug” and the WG agrees, and makes it an erratum, that

> >> they should say to X at least “we agree” and follow-up when there is

> >> a fix, and point X at where they can see the bug and the fix being

> >> tracked?  That seems obvious to me…

> >>

> >> Chaals, if we add that the integrated document approach is a best practice,

> and clarify the last paragraph, would this text also address your concerns?

> >

> > Not the ones about defining errata, nor about verbosity.

> >

> > I realise we have had the verbosity discussion several times about a few

> paragraphs, and a few paragraphs won't make a big change. But proposing a

> rewrite that trims significant amounts not unreasonably leads to a discussion

> because it is hard to understand the full impact of the changes. If we can't

> reduce the size of the document a few sentences at a time, and we can't

> reduce it in large chunks, I think we have a serious problem.

> >

> >>>>  7.7.1 Errata Management

> >>>>

> >>>>  Tracking errors is an important part of a Working Group's ongoing care of

> a Recommendation; for this reason, the scope of a Working Group charter

> generally allows time for work after publication of a Recommendation. In this

> Process Document, the term "erratum" (plural "errata") refers to any error that

> can be resolved by one or more changes in classes 1-3 of section 7.2.5 Classes

> of Changes.

> >

> > I would keep the first sentence and drop everything from "for this reason" on.

>

> I would not.  I don’t mind deleting ‘for this reason’ because it’s informative

> fluff.

>

> >

> >>>>  A Working Group must keep a record as errors are reported by readers

> and implementers. Such error reports should be processed no less frequently

> than quarterly. Readers of the Recommendation should be able easily to find

> and see the errata that apply to that specific Recommendation.

> >

> > I think this is redundant (the specifics are requirements for issue, and

> changes, respectively) but can live with it.

> >

> >>>>  Working groups may decide how to document errata. Examples of

> acceptable errata management include an errata page, possibly auto-generated

> from a database, or a document that identifies itself as based on the

> Recommendation text and clearly identifies the errata and any proposed

> corrections.

> >>>>

> >>>>  An erratum is resolved by an informative, "proposed" correction

> generated by the Working Group  A correction becomes a normative part of

> the Recommendation by the process for Revising a Recommendation described

> in the next section.

> >

> > The first sentence strikes me as wrong, without adding anything.

>

> which first sentence?  the one that leaves choice of mechanism to the WG, or

> the one that says that any correction is only “proposed” until a revised

> document is steered through the process?  They both seem true to me…

>

> > The second sentence is repeating the obvious if you read another couple of

> lines - or even happen to glance at the heading subconsciously.

> >

> >>>>  A Working Group must report changes that incorporate errata to

> >>>> interested parties, notably when corrections are proposed or

> >>>> incorporated into an Edited Recommendation, according to the Team's

> >>>> requirements. [[huh??]]

> >

> > This is a requirement for issues and changes anyway, so is redundant, and

> just increases the text in this section to no apparent benefit. I would remove it.

>

> me too

>

> >

> > cheers

> >

> > Chaals

> >

> >>>>>  On Jan 13, 2015, at 10:25 , Jeff Jaffe <jeff@w3.org<mailto:jeff@w3.org>> wrote:

> >>>>>

> >>>>>  On 1/13/2015 12:12 PM, chaals@yandex-team.ru<mailto:chaals@yandex-team.ru> wrote:

> >>>>>>  Hi,

> >>>>>>

> >>>>>>  I took action-141 because I disagreed with Steve's November proposal

> for errata [1]. In today's meeting Steve asked us to respond to that proposal

> and explain objections and changes that would address them.

> >>>>>>

> >>>>>>  The proposed replacement text for section 7.7.1 is [[[  Tracking

> >>>>>> errors is an important part of a Working Group's ongoing care of a

> Recommendation; for this reason, the scope of a Working Group charter

> generally allows time for work after publication of a Recommendation. In this

> Process Document, the term "erratum" (plural "errata") refers to any error that

> can be resolved by one or more changes in classes 1-3 of section 7.2.5 Classes

> of Changes.

> >>>>>>

> >>>>>>  A Working Group should keep their Recommendations up-to-date as

> errors are reported by readers and implementers. Such error reports should be

> processed no less frequently than quarterly and errata should be placed in the

> Recommendation.

> >>>>>>

> >>>>>>  An erratum is resolved by an informative, "proposed" correction

> generated by the Working Group  A correction becomes a normative part of

> the Recommendation by the process for Revising a Recommendation described

> in the next section.

> >>>>>>

> >>>>>>  There are two ways in which the errata and/or proposed corrections

> may be placed in the Recommendation. First, the Recommendation may point

> to a page in which the errata (and any proposed corrections that fix the

> erratum) are incorporated in an identifiable way. Alternatively, the

> Recommendation may be edited to allow a viewer to selectively display: (a) the

> original content of the Recommendation, or (b) that content updated to show

> the corrected text. Either of these approaches MUST satisfy the then applicable

> Publication Rules.

> >>>>>>

> >>>>>>  A Working Group must report changes that incorporate errata to

> interested parties, notably when corrections are proposed or incorporated into

> an Edited Recommendation, according to the Team's requirements.

> >>>>>>  ]]]

> >>>>>>

> >>>>>>  Responding paragraph by paragraph:

> >>>>>>   1. The first sentence boils down to "bugs have to be tracked when you

> find them, even after recommendation". I agree that the process should set

> that expectation. The second sentence attempts to define errata specific to

> W3C process, because that distinction is used later in the proposal. I do not

> think that defining them specifically is useful, and as explained below I do not

> think the use for the specific definition is helpful.

> >>>>>>

> >>>>>>  2. The first sentence assumes that a Recommendation belongs to a

> Working Group, which is false.

> >>>>>  I agree that a clarification would be helpful.  Perhaps something like:

> >>>>>

> >>>>>  A Working Group should make it easy for the community to find errors

> reported by readers and implementers together with suggested corrections.  A

> best practice would be to create a document which contains suggested

> corrections alongside the original Recommendation text; with clear markings

> (e.g. different colors) what is the Recommendation text and what are the

> suggested corrections.

> >>>>>>   A Recommendation is a Recommendation of the W3C developed

> through a consensus process. The Working Group does the "grunt work" of

> proposing what that should be in detail, but it is not a W3C Recommendation.

> That said, the process is intended to allow W3C to produce Recommendations

> that are useful - and this means that for the lifetime of a technology it is

> probable that there will be value in providing corrections, enhancements, etc.

> That is the point of being able to revise a Recommendation, and the fact that it

> should happen is already covered in the first sentence of paragraph 1.

> >>>>>>  Specifying a particular rhythm is saying in another way what is in 7.2.1

> (we could just link there).

> >>>>>  I don't see the harm in listing the quarterly expectation here.

> >>>>>>   I strongly object to the suggestion that errata (statement and/or

> proposed resolution) should go directly into a Recommendation, rather than

> some other document such as an errata list, bug tracker, draft replacement

> version, etc. (I'll return to this in regards to paragraph 4).

> >>>>>  I believe that the intent was that it would be a draft replacement

> version.  Clearly the text that has not been through the process does not rise to

> the level of Recommendation text.

> >>>>>>  3. This paragraph doesn't add anything useful, and could be scrapped.

> There is an existing discussion of how issues are resolved, and a "proposed"

> correction is merely an attempt to provide a formal title to a proposed

> resolution of a bug or issue.

> >>>>>  Fair point.  I believe that the purpose of this paragraph was merely to

> emphasize that the text of a proposed correction (when it sits in one of these

> "draft replacement versions" - or whatever we call them) does not have

> Recommendations stature until it goes through the Revision process.  There

> are probably editorially superior ways to phrase this; especially in view of the

> comments above.

> >>>>>>  4. There are at least 3 useful ways to track issues raised against a

> document, and the proposals made, and accepted by the working group, to

> resolve them. Putting them into an errata list, putting them in a bug or issue

> tracker, and putting them into a draft document are all reasonable alternatives.

> None of them involve touching the text of a W3C Recommendation.

> >>>>>  I think these are all reasonable ways to track issues and what is

> accepted by the WG.

> >>>>>

> >>>>>  The input that the task force received last year was that the particular

> idea of threading the proposed changes into the Recommendations text would

> be of particular value to readers. That was the proposal that we went with

> earlier.  I think this should at least be identified as a best practice.

> >>>>>>   In addition, setting a constraint for "classes 1-3 of change" (as defined

> in section 7.2.5, i.e. those which do not involve a new feature [2]) but requiring

> that it not be applied to class 4 (new features) introduces a layer of busywork

> for a group that has a sensible way of updating documents in a timely manner

> and informing people of changes they are proposing for the specifications they

> manage.

> >>>>>  Whether or not this is busywork depends a fair bit on how quickly the

> group can get out new features.  We don't have a great track record for new

> features (HTML took over 10 years) so being more agile for classes 1-3 seems

> essential.

> >>>>>>  The second sentence is reasonable as *a suggestion* for ways to

> manage errata. Although there are many situations where that approach has

> been found to be problematic, meaning it should not be *mandated* there are

> also ways to use it reasonably, meaning it should not be forbidden.

> >>>>>>  Proposing to incorporate new material that has not been reviewed by

> W3C into a Recommendation strikes me as an incredibly bad idea. W3C has

> long maintained a social contract that the text of a Recommendation will not

> change. Publishing them as static documents without multiple viewing options

> is an important part of ensuring that there is not confusion about what is the

> text of the Recommendation. Changing that seems a terrible idea. Publishing

> e.g. an editor's draft for a replacement version (something that W3C has also

> been doing for almost a couple of decades), or using some other means of

> tracking proposed changes that have not been approved by W3C, and clearly

> linking it from the Recommendation, seems a perfectly adequate mechanism of

> informing people about the latest ideas while providing a simple, reliable and

> stable reference for those who need one.

> >>>>>  Some of this argument is one of semantics.  I see tremendous value in

> the proposed idea of embedding the current thinking about proposed changes

> into the text of the Recommendation.  For my pov, we don't need to call this a

> Recommendation at all.

> >>>>>>  In addition, while there are various mechanisms to identify two

> different views of a single document, such as the use of extra styles, they are

> less reliable than simply having two different documents e.g. a

> Recommendation and an Editor's Draft. In any event, where there are class 4

> changes being proposed at the same time, it makes no sense to *require* a

> version that does not make them available while presenting class 1-3 proposed

> changes.

> >>>>>  See above.

> >>>>>>  5. The requirement to inform "interested parties… according to the

> Team's requirements" is redundant with the requirement in the subsequent

> section 7.7.2 (first bullet in the list in that section), but without the explanation

> of what that means which is provide for the term "wide review".

> >>>>>>

> >>>>>>  To summarise, the features of the proposal I explicitly object

> >>>>>> to are

> >>>>>>  - Anything that suggests adding material to a published

> >>>>>> Recommendation (as opposed to an Editor's draft or other separate

> >>>>>> document with a different status)

> >>>>>>  - Redefining the term "errata"

> >>>>>>  - Forcing groups to use different mechanisms for different types

> >>>>>> of issue, beyond constraints in the existing process outside

> >>>>>> section 7.7.1

> >>>>>>  - The use of different text from elsewhere in the document in

> >>>>>> the final sentence

> >>>>>>  - The verbosity of the section

> >>>>>>  - Constraining the way groups present issues and proposed

> >>>>>> resolution of them beyond the existing Process outside section

> >>>>>> 7.7.1

> >>>>>>

> >>>>>>  The parts that I find neither objectionable nor unnecessary

> >>>>>> repetition are

> >>>>>>  - a statement that publishing a Recommendation doesn't mean the

> responsibility of a working group to record and address issues has been

> discharged.

> >>>>>>  - allowing the use of an errata page as one means of tracking issues

> raised against a Recommendation.

> >>>>>>  - the idea (implicit but unstated) that it should be easy to find the

> issues raised against a recommendation and solutions proposed for them.

> >>>>>>

> >>>>>>  It seems that these three points could be more succinctly expressed in

> a single introductory paragraph, and we could remove section 7.7.1 and the

> section 7.7.2 header entirely header If people like that idea, I will propose some

> specific text.

> >>>>>>

> >>>>>>  cheers

> >>>>>>

> >>>>>>  [1]

> >>>>>> https://lists.w3.org/Archives/Public/public-w3process/2014Nov/000


> >>>>>> 4.html

> >>>>>>

> >>>>>>  --

> >>>>>>  Charles McCathie Nevile - web standards - CTO Office, Yandex

> >>>>>> chaals@yandex-team.ru<mailto:chaals@yandex-team.ru> - - - Find more at http://yandex.com


> >>>>  David Singer

> >>>>  Manager, Software Standards, Apple Inc.

> >>

> >> David Singer

> >> Manager, Software Standards, Apple Inc.

> >

> > --

> > Charles McCathie Nevile - web standards - CTO Office, Yandex

> > chaals@yandex-team.ru<mailto:chaals@yandex-team.ru> - - - Find more at http://yandex.com


>

> David Singer

> Manager, Software Standards, Apple Inc.

>