RE: Review of ordering draft, version 05

I still feel strongly that postconditions (and ideally also
preconditions) should be explained as full English sentences

For example, replace

  "(DAV:ordering-type-set): the collection was created with the
specified ordering type. "

With

  "(DAV:ordering-type-set): The server MUST set the ordering-type
  property on the new resource to the value specified in the
Ordering-Type
  header by the client. If it cannot, this error should be used."

I will propose specific text for every postcondition if necessary.

Lisa

> -----Original Message-----
> From: w3c-dist-auth-request@w3.org 
> [mailto:w3c-dist-auth-request@w3.org] On Behalf Of Julian Reschke
> Sent: Thursday, February 13, 2003 12:25 PM
> To: Webdav WG
> Subject: RE: Review of ordering draft, version 05
> 
> 
> 
> Hi.
> 
> I have adressed some of Lisa's issues, in particular:
> 
> - how to interpret the DTD fragments [1]
> - reference to RFC3253 pre/postcondition definition [2]
> 
> I've also tried to clarify the relation to versioned collection ([3]).
> 
> To those who revieved the 05 draft: please check out the 
> current version
> (all changes are highlighted) -- I intend to submit this 
> draft as "last
> call" version early next week.
> 
> Julian
> 
> 
> [1]
> <http://greenbytes.de/tech/webdav/draft-ietf-webdav-ordering-p
> rotocol-latest
> .html#rfc.section.1>
> [2]
> <http://greenbytes.de/tech/webdav/draft-ietf-webdav-ordering-p
> rotocol-latest
> .html#rfc.section.3>
> [3]
> <http://greenbytes.de/tech/webdav/draft-ietf-webdav-ordering-p
> rotocol-latest
> .html#rfc.section.9>
> 
> --
> <green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760
> 
> > -----Original Message-----
> > From: w3c-dist-auth-request@w3.org
> > [mailto:w3c-dist-auth-request@w3.org]On Behalf Of Lisa Dusseault
> > Sent: Saturday, February 08, 2003 6:46 PM
> > To: 'Julian Reschke'
> > Cc: Webdav WG
> > Subject: Review of ordering draft, version 05
> >
> >
> >
> >
> > Since we're getting close to last call on the ordering 
> draft, I reviewed
> > it all again (it's been years since I did so before).  Here 
> are all my
> > comments.
> >
> > Section 3:
> > "This document uses the terms "precondition" as "postcondition" as
> >    defined in [RFC3253]. "
> >
> > Should be "and", not "as"
> >
> > I don't think it's sufficient to just import the definitions of
> > precondition and postcondition. These are concepts that can clarify
> > what's going on, but unless it's accompanied by really 
> plain English,
> > future readers of the specification won't be able to extract the
> > information they need. Long-timer WG participants may know 
> the meaning,
> > but I'm learning more and more about people who never come to the
> > working groups, who may only read little pieces of our 
> specifications
> > (e.g. a developer who doesn't usually do protocol 
> implementation but is
> > assigned to fix a bug).  Server implementors won't bother verifying
> > whether some condition is one they have to enforce, or 
> simply ignore it.
> > I strongly recommend including the standard MUST/MAY/SHOULD language
> > that specification readers are familiar with, particularly in the
> > postconditions which are not just error code definitions but also
> > specify behavior.
> >
> > As an example, I'll jump ahead to the first precondition and
> > postcondition in section 5.1.  I'm not even sure what they mean, but
> > I'll try to guess in order to restate them. Here's what I'd 
> like to see:
> >
> >  Additional Preconditions:
> >
> >       (DAV:ordered-collections-supported): Error used when 
> the client
> > attempts to create an ordered collection, if the server 
> does not support
> > the creation of ordered collections in this namespace.
> >
> >   Additional Postconditions:
> >
> >       (DAV:ordering-type-set): The server MUST set the ordering-type
> > property on the new resource to the value specified in the 
> Ordering-Type
> > header by the client. If it cannot, this error should be used.
> >
> > That's just a sample; all of the postconditions and 
> preconditions need
> > to be full sentences explaining what must or may happen.
> >
> > Section 5.1:
> > "If the Ordering-Type header is not present, the collection will be
> > unordered."
> >
> > "Will be" is ambiguous standards language.  It implies MUST 
> but doesn't
> > really require anything.  "... the server MUST create the 
> collection as
> > unordered" is one possibility. However, it's fine to say "... the
> > collection MAY be created as unordered" if we want to give 
> servers the
> > freedom to make new collections ordered by default.
> >
> > Section 5.1: I don't see how the ordering-type-set 
> postcondition can be
> > implemented. How can the server tell the difference between 
> an ordering
> > type that it must support, or an ordering type that it's 
> not supposed to
> > know about but just advertise?
> >   Or is the server just supposed to set the value, period?  
> If that's
> > the case, then why isn't this simply a MUST requirement, 
> rather than a
> > postcondition?
> > I suspect I don't really understand the ordering-type-set 
> postcondition,
> > thus it probably just has to be explained more in the specification.
> >
> >
> > Section 6.1
> > The "segment" definition in BNF is imported from RFC2396.  But that
> > definition says that a segment can contain a "param":
> > 	RFC2396
> > 	  "segment       = *pchar *( ";" param )"
> >
> > What would the param be or mean?  I suspect we'll have to 
> define our own
> > here.
> >
> > " The server MUST insert the new member into the ordering at the
> >       location specified in the Position header, if one is 
> present (and
> >       if the collection is ordered)."
> >
> > What does the "one" refer to in "if one is present"?  I 
> think this means
> > "If the collection is ordered and a new member is inserted with the
> > Position header, the server MUST insert the new member into 
> the ordering
> > at the location specified in the header."
> >
> > " (DAV:collection-must-be-ordered): the target collection must be
> >       ordered."
> >
> > Does this mean that the request to PUT a resource *fails* 
> if the client
> > includes a Position header and the collection isn't ordered?  That's
> > expensive for a client to have fail.  I don't know if 
> that's what client
> > implementors are going to want to happen.
> >
> > "    (DAV:segment-must-identify-member): the referenced segment must
> >       identify a resource that exists and is different from 
> the affected
> >       resource."
> >
> > Again, does this mean the server MUST fail the PUT request if the
> > segment in the Position header doesn't exist?
> >
> > "     (DAV:position-set): the newly created collection member was
> >       created at the specified position."
> >
> > Shouldn't the server always create the new member at the specified
> > position (a MUST)? Under what circumstances would this ever 
> not happen?
> >
> > Specification organization: how about putting the Position and
> > Ordering-Type header definitions in their own sections, 
> titled "Position
> > Header" and "Ordering-Type Header". That makes it easier 
> for people to
> > use the specification as a reference.
> >
> >
> > Section 7.
> >
> > "     <!ELEMENT orderpatch (ordering-type?, ordermember*) >"
> >
> > This definition makes the orderpatch element (thus the ORDERPATCH
> > request body) non-extensible unless we say otherwise.  We 
> could put in
> > the "elements not understood by the server MUST be ignored" 
> language, or
> > redefine certain elements as
> >
> >       <!ELEMENT orderpatch (ordering-type?, ordermember*, ANY) >
> >
> > We need to say that the list of <ordermember> elements in 
> the orderpatch
> > body is itself order-dependent -- I believe the server must 
> process them
> > in the order they appear, first to last.  Actually, this is 
> specified in
> > section 7.1 under the example, but it should be said in section 7.
> >
> > "      (DAV:orderding-modified): if the request body contained
> >       DAV:ordermember elements, the ordering of internal 
> member URIs in
> >       the collection identified by the request-URI has been changed
> >       based on instructions in the DAV:ordermember elements."
> >
> > Isn't this a simple MUST rather than a postcondition?  "The 
> server MUST
> > order internal member URIs in the collection identified by the
> > request-URI based on instructions in the DAV:ordermember 
> elements in the
> > ORDERPATCH request body." Under what conditions would this
> > ordering-modified error be returned to the client?
> >
> > Section 7.2.
> >
> > This example shows what happens if the fourth <segment> 
> element in the
> > request body does not name a valid segment.  By analogy, I 
> can see what
> > would be returned if the second <segment> element were 
> invalid. However,
> > I'm not clear what would happen if the first or third 
> <segment> element
> > were invalid.  What would be returned in the <href> element 
> in the error
> > response?
> >
> > "Because ORDERPATCH is an atomic method, the request to
> >    reposition nunavut.desc (which would otherwise have 
> succeeded) failed
> >    as well, but doesn't need to be expressed in the 
> multistatus response
> >    body."
> >
> > One of the things we've learned from RFC2518 
> interoperability is that's
> > not necessarily true. When a server does a MOVE on a collection, the
> > client has a hard time figuring out which things moved and 
> which didn't.
> > Some responses have the failed dependency error, others 
> don't.  Should
> > we consider being more specific here? The server could 
> simply include a
> > 424 Failed Dependency error for each ordering that failed 
> because of the
> > atomicity of the method.
> >
> > Section 9.1.
> >
> > "The property DAV:version-controlled-binding-set ([RFC3253], section
> >    14.2.1) records the set of version-controlled bindings in the
> >    collection. For ordered collections, the DAV:version-controlled-
> >    binding elements MUST appear in the ordering defined for 
> the checked-
> >    in ordered collection."
> >
> > This is true only for working collections when versioned 
> collections are
> > supported. At a minimum, change to:
> >
> > "The property DAV:version-controlled-binding-set ([RFC3253], section
> >    14.2.1) records the set of version-controlled bindings in a
> >    working collection (part of the versioned collections feature).
> >    For an ordered working collections, the
> >    DAV:version-controlled-binding elements MUST appear in 
> the ordering
> >    defined for the associated checked-in ordered collection."
> >
> > Doesn't that mean that the user can't reorder a collection 
> that they've
> > checked out into a working collection?
> >
> > Section 10 (Discovery).
> >
> > "  Furthermore, RFC 3253 [RFC3253] introduces the live properties
> >    DAV:supported-method-set (section 3.1.3) and DAV:supported-live-
> >    property-set (section 3.1.4). Servers MUST support these 
> properties
> >    as defined in RFC 3253."
> >
> > Do you mean that any server that supports this specification must
> > support these two RFC3253 properties as well? If so, that 
> could be made
> > a little more clear like this:
> >
> > "  Furthermore, RFC 3253 [RFC3253] introduces the live properties
> >    DAV:supported-method-set (section 3.1.3) and DAV:supported-live-
> >    property-set (section 3.1.4). Servers supporting 
> ordered-collections
> >    MUST support these properties as defined in RFC 3253 even if the
> >    server does not support any RFC3253 features."
> >
> > Section 16. Acknowledgements
> >
> > "Lisa Lippert" was me, but my name is now "Lisa Dusseault" 
> again...  I'd
> > much prefer to be listed as Dusseault!
> >
> > Lisa
> >
> >
> 
>

Received on Thursday, 13 February 2003 20:24:18 UTC