Subject: RE: PaceMinimalVersioning

From: "David Orchard" <[email-masked]>
Date: Thu, 16 Sep 2004 11:14:49 -0700

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]]
> Sent: Thursday, September 16, 2004 9:50 AM
> To: David Orchard
> Cc: Atom-Syntax Syntax
> Subject: Re: PaceMinimalVersioning
> 
> On Sep 16, 2004, at 9:12 AM, David Orchard wrote:
> 
> > I find PaceMinimalVersioning incomplete and inconclusive and found
no
> > illustration or exploration of extension mechanisms.
> 
> PaceMinimalVersioning provides a simple, concrete, easily-implemented
> set of rules telling software exactly what it can and must do in the
> face of errors and unrecognized markup.  Perhaps you could outline a
> use-case in which it isn't crystal-clear what a software implementer
> can do and what someone sending Atom data can expect?
> 

So you want the rules only and no explanatory text.  OK, I've created 
http://www.intertwingly.net/wiki/pie/PaceExtensibilityAndVersioningNoSce
narios.  This provides a simple.... 

Is your concern that my statement "A Fault must be generated if any
element marked mustUnderstand is not understood." isn't strong enough so
you came up with " If software processing an Atom document encounters an
unrecognized element which has the "atom:must-understand" attribute
present with a value of "true", it MUST report an error and cease
processing. "?

> I further claim that to the extent you can decouple the extension
> mechanism from the handling of versioning and unrecognized markup, you
> win.  If someone wants to post another Pace describing extensibility
> mechanisms that allows the simple, unsurprising, easy-to-implement
> behavior specified in PaceMinimalVersioning, then that would be a very
> attractive extension mechanism.  And to the extent it requires
anything
> more complex, I'm probably -1. -Tim

Please provide rationale for why version #s are simpler, unsurprising,
easy-to-implement behavior compared to namespace names.  

Cheers,
Dave

---

From: Tim Bray <[email-masked]>
Date: Thu, 16 Sep 2004 12:10:07 -0700

> narios.  This provides a simple....

URI without linebreaks:  
http://www.intertwingly.net/wiki/pie/ 
PaceExtensibilityAndVersioningNoScenarios

OK, either I was having a stupidity attack (quite possible,  
Vancouver->Brussels->Vancouver->SanFran->Sebastopol->Valley->Vancouver  
in 10 days with lots of heavy meetings will do that to you) or the  
clouds of scenarios were getting in the way.  I'm generally +1 on  
PaceExtensibilityAndVersioningNoScenarios, but want to suggest some  
mods:

1. PaceMinimalVersioning described a condition called an Atom Error,  
e.g. you're processing atom 1.0 and you encounter an "<atom:foo>"  
element where atom:foo isn't defined by the 1.0 format spec.  My  
suggestion was that software SHOULD report it and MAY cease processing  
and if it doesn't cease, MUST ignore.  Maybe this goes somewhere else,  
does this need a separate Pace?  I do think it's important to  
acknowledge the existence of this kind of error and say something about  
what happens.

2. A required "version=" attribute on the root element is generally  
useful for implementors and human readers and not actively harmful.   
Especially given that there are lots of 0.3 feeds out there and that  
software will want to distinguish.  Also, this allows us to give a  
definition of "Atom Error".

3. I think the namespace-handling text can be simplified and clarified,  
along these lines:

New section 7.

- lose the 2nd sentence of 1st para, which ends "...this is called  
versioning."  Reason: it uses the not-widely-known term "qname", and it  
says that version 1.1 of Atom isn't actually a "version" if it uses the  
same namespace, which is kind of confusing.  I don't think this helps  
implementors.

7.1 Processing Model

- Lose the sentence about processing none or all of mustUnderstand.  In  
fact, it must process all or report an error, right?

7.2 Versioning and Namespace Policy

- Rewrite 1st para:

Future versions of Atom will not change the semantics of Atom elements  
or attributes in such a way that the software implementations for  
previous versions are incorrect.  Thus, if a future version introduces  
an incompatible change, it must do so by introducing a new element in  
the same namespace, or using a new namespace name (which in effect  
changes the names of all the elements).  However, for example, adding a  
new optional element or attribute does not require changing the  
namespace name.

[Question: is the mustUnderstand attribute namespace-qualified, e.g.  
atom:must-understand?  I think so, because you can use it on an  
extension from another namespace]

- 2nd para as-is

7.3 Atom third party extensibility

Lose "They MUST use namespace names they control."  What does "control"  
mean, since a namespace name is an arbitrary URI?  And all we really  
care about for protocol purposes is that they use namespaces other than  
Atom's (which you already said above).  The suggestion about control is  
correct but requires a longer write-up and belongs in a best-practices  
doc or implementor's guide.  -Tim