Proposal for Publishing REC Errata

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.

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

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.

   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.

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.

~fantasai

Received on Wednesday, 15 October 2014 02:32:50 UTC