Re: ACTION-350: Best practice for referring to specifications which may update

Hi Larry,

On Jan 18, 2012, at 14:54 , Larry Masinter wrote:
> Larry:
>> What is too complex and ultimately wrong  is to give options to those 
>> writing specs that make references.
> 
> Robin:
>> I beg to differ. Ultimately, those who write specs are those most 
>> informed about how they should handle their own references
>> (if they're not, then we have an entirely different problem). 
>> They are the ones who should be making decisions about whether
>> the specifications they reference can be trusted to remain compatible
>> and should therefore be loosely bound, or on the contrary (hopefully 
>> only in extreme cases) have a broken upgrade path and need an anchored reference.
> 
> I don't think it is an "entirely different problem", I think it is the
> essential problem we have to fix. 

Actually I think we're talking about entirely different different problems there, but I believe we can get on the same page below.

> Specs have editors, reviewers, and implementors. 
> The workflow is that editors write the specs, reviewers review it for
> implementability and interoperability and IPR and other values,
> and implementors implement the spec (later). 

Ideally the iteration loop should be tighter than that here, but for purposes of assuming a worst-case scenario I agree that we can take this as our base situation.

> I agree that it *should* be the case that those making the reference
> *should* be able to judge the stability and likely growth of the
> specs that they reference.
> 
> However, even with best of intentions, things happen,
> (1) specs have errors and you should be able to correct them. 
> (2) new extensions are both useful and harmless, you should be
> able to use them, but
> (3) people get carried away with enthusiasm, and stuff gets added
> or changed in B in a way that is harmful or disruptive to A.

Yes, or more generally: specs evolve, and we should be able to handle it gracefully. To be honest, where this topic is concerned, while I agree that establishing best practice in references is somewhat useful the far more useful side of the topic is to establish best practices for specification evolution so as not to break things. There was interesting work on versioning in TAG antiquity that might use some dusting off, and there's little in the way of discussion for API versioning strategies (which came up as a request from the developer community at TPAC, in the form of feature testing).

>> Of course editors need to be aware of this decision in the first place, 
> 
> Which decision? That the editors have the responsibility to predict events
> in the future that are completely outside their control?

No, but editors do have the responsibility to assess whether a specification that they're referencing is stable, and whether it appears to be produced by people who are likely to respect forward compatibility or not. Obviously, things can still go wrong but I don't think that there's a best practice that can address that at the reference level.

>> I think that Henry's original proposal captures the two important pieces of 
>> information: the version of referenced specifications against which the WG
>> developed (and tested),
> 
> I agree this is important, but note that it removes from editors the option 
> of not saying this at all.... what if the editors would rather make an undated
> normative reference to a living standard?

My reading of Henry's proposal is not that it prevents this at all. The boilerplate from his proposal that could be added to the references section reads:

    Dated references below are to the earliest known or appropriate
    edition of the referenced work.  The referenced works may be
    subject to revision, and conformant implementations may follow,
    and are encouraged to investigate the appropriateness of
    following, some or all more recent editions or replacements of the
    works cited.  It is in each case implementation-defined which
    editions are supported.

In other words: we refer to a specific version (so that you know what we developed against) but implementations are expected to use revisions thereof where applicable. It could use some word-smithing to indicate that when a reference is made to an undated version, it is intentional, but I see that more as tweaking his proposal than as being radically different from it.

In essence, I get the sense that you're largely agreeing with Henry's proposal, or at least I'm failing to see where you disagree. I think it needs tweaking, but is overall pointed in the right direction.

Note that throughout this discussion, I've seen people use what I believe is an overly simplistic model in order to capture referential dependencies. If all you have is spec A referencing spec B, and you're only implementing spec A then we can argue about the relative merits of referencing B-v2 or B-v* but at the end of the day it'll boil down to the specifics of what spec A is importing from B and how exposed it is to potential changes. It's a trivial scenario, and not one where I feel we can do much to help.

A more real world scenario is when you've got two specifications referencing a third one, and both of the first are supported together in the same implementation. So say for instance that you have the Unicorn specification, and the Dahut specification, both reference the Shiny Magical Powers specification, and what you're implementing is a Cryptozoology application.

If Unicorn and Dahut reference different static versions of Shiny Magical Powers, then at best you've got a painful implementation which needs to support both versions concurrently, but in practice the chances are very high that that's not even technically possible, so that you'll have to have both use at the very least the highest static version being referenced by either.

Of course, a scenario in which we just have two specifications referencing a third one is still unrealistically simplistic. In practice, where the Web in concerned, even without reaching for the kitchen sinks that browsers are, you're dealing with a massive interdependent graph of specifications (I'd love for someone with spare time on their hands to visualise that). So references to if not "living standards" (skirting around that specific controversy) at least standards expected to evolve is the only viable practice.

> Shouldn't that be an option? If you trust the people editing B that
> they'll not make incompatible changes that will cause you a problem?

Not just an option but the default unless you have really good reasons to do it in any other way. *But* it's still useful to document which version you were using when you made the reference. This is for debugging purposes: when something goes wrong down the line, we can figure out why more easily.

That's why I think that Henry's proposal of essentially (unless I misread it) "this is the version we used, but we expect it to evolve" seems like the best practice for references to me.

-- 
Robin Berjon - http://berjon.com/ - @robinberjon

Received on Wednesday, 18 January 2012 17:07:11 UTC