Re: Time for publication?

Ian Hickson <ian@hixie.ch>, 2008-05-09 07:19 +0000:

> On Fri, 9 May 2008, Michael(tm) Smith wrote:
> > 
> > That said, I don't think we should just publish an updated draft of the 
> > spec without also publishing a "changelog" or "release notes" document 
> > that provides high-level descriptions of the substantive (non-editorial) 
> > changes that have been made to spec since the FPWD.
> 
> I'm all for that... who should take ownership of that deliverable, and how 
> long would creating such a document take? (i.e. how long should we 
> resonably wait before deciding that we should publish the spec anyway?)

I will take ownership for it myself, and will aim to have a
complete draft of it (complete as in, attempting to document all
substantive changes since the FPWD) by May 23 (if not sooner).

If that sounds like too long to take to write it up, consider that
the intent of it (if I write it up at least) will be, for each
change, to provide readers with at least some minimal
understanding of the context of the part/feature of the document
in which the change was made.

For example:

  The following changes were made to the Links section after FPWD
  publication. 

  4.12.2.1. Hyperlink auditing, requests must not include a Referer
  HTTP header, etc.

  (r1170, r1.362) The 4.12.2.1. Hyperlink auditing section of the
  specification states requirements for HTTP-request behavior when a
  user follows a hyperlink for an <a> or <area> hyperlink element
  that has a ping attribute. 

  That section was changed to now say that:

    For URIs that are HTTP URIs, the requests must be performed using
    the POST method (with an empty entity body in the request). The
    requests must not include a Referer HTTP header, cookies, or HTTP
    authentication headers. 

  The reason for the change was to fix a potential security flaw
  related to the ping attribute. For details, see the Referer header
  sent with <a ping>? thread on the WHATWG mailing list.

If that seems like an unnecessary level of detail or it turns out
to be overly ambitious to try to document all the changes since
the FPWD in that level of detail, then I guess I could end up
needing to scale the plan back a bit to get it done within a
reasonable amount of time.

  --Mike

P.S. Going forward, we should really talk about coming up with a
process for getting those kinds of "amplified" explanations of
changes to the spec documented in that way as they get checked in,
instead of needing to stop again next time and take significant
time to get them documented weeks or months after the fact.

As far as writing and maintaining the record of those "amplified"
explanations, I think that will require having some people step
forward to volunteer...

-- 
Michael(tm) Smith
http://people.w3.org/mike/
http://sideshowbarker.net/