RE: Part 1, Comments on draft-ietf-deltav-versioning-12.2

   From: Larry Masinter [mailto:LMM@acm.org]
   Cc: Dan Brotsky

   I've only gotten through the first 9 pages of typing in comments,
   so I think I better chunk these and send what I have.

Dan: We *really* appreciate a review at this level of detail,
especially by a new pair of eyes that haven't already seen it dozens
of times.  And thanks to Larry for typing the comments in for the
mailing list!

   I *think* that most of these comments are editorial; that is, there
   are sentences and phrases in the draft that are confusing, and it
   is quite possible that the confusions could be cleared up
   editorially without changing the protocol.

That does appear to be the case for this first chunk of comments.

   However, it is often the
   case that confusing or ambiguous wording hides errors in
   protocols.

Confusing or ambiguous wording is bad, whether or not it
hides errors (but it is even worse if it does, of course).

   In general, the document is very hard to read. You might
   argue that "well, we understand it, and that's good enough." And on
   the phone conference I got some of this pushback, "we tried
   clarifying this before with examples and the examples confused
   other people".

It's important to distinguish "we understand it and that's good
enough", which would be a completely unacceptable attitude, from "we
tried clarifying it the way you describe, and it confused more people
than it helped", which is just an explanation of why a certain change
might be undesireable (but is of course not justification for leaving
it unfixed).  But none of Dan's comments fall into this category
of "tried it already" (at least, so far), so he's provided us with
valuable new insight into what could be improved.

   But there is no point in bothering with the IETF process if all you
   are going to wind up with is a document that only the authors and
   working group members understand.

I agree.

   The value that you get from "IETF
   Proposed Standard" comes with a price: writing something that
   ordinary implementors can sit down and code to. I don't think it's
   impossible to document this protocol clearly.

I agree with this as well.  (I assume by "ordinary implementors",
you mean implementors that know how to implement either a versioning
client or a versioning server, and expect the protocol to explain
how to marshall the communication between a versioning client
and a versioning server in an interoperable way).

   Specific comments:

   1. "This document defines WebDAV Versioning extensions, an
    application of HTTP/1.1 ..."

   But the "WebDAV Versioning extensions" are not, by themselves, an
   application of HTTP/1.1. The WebDAV Versioning extensions are a set
   of extensions to WebDAV, which, in turn, is a set of extensions of
   HTTP/1.1 ...  In general, the relationship between the versioning
   extensions, WebDAV and HTTP/1.1 needs to be stated clearly. To use
   Versioning extensions, you need to implement WebDAV; to implement
   WebDAV, you need also to implement HTTP/1.1.

It sounds like the "application of" language is misleading, and if
we just said that the WebDAV Versioning provides extensions to WebDAV,
it would be clearer?  The "Relationship to WebDAV" section then goes
into more detail.

   2. "All core versioning functionality MUST be provided by a server
   that supports versioning."  In general, a conformance requirement
   MUST needs to have a definable scope and interpretation. Right now,
   the definition of "core versioning" is circular; it's defined in
   terminology as "the set of properties and semantics that MUST be
   supported" but that set is defined by the term "core versioning". I
   think you actually want to define "core versioning" by something
   like "the set of methods in Section 2, making reference to the
   terms in section 1.4 but without needing any of the terms in
   section 1.4.1."

Good point!  I will make that change.  Also, while I'm in there,
it probably makes sense to follow Chuck's suggestion (I believe it
was Chuck ...) which was to move the "option terms" forward to
an "options" section.  This would simplify the introduction,
and avoid the "without needing 1.4.1" complication.

   Actually, there's no definition of "a server that supports
   versioning".  A few of the terms in 1.4 mention "server", but the
   relationship between resources and the servers that serve them
   isn't clear.

I'll get rid of the specific reference that you identify above.
The term server is defined in 2616, and I believe that usually
we are using it in the standard sense (i.e. a server is something
that services requests on a resource).  I'll make a pass through
the document looking at where we use the term "server" to see
if they can be changed.  If there are any other specific places
which you feel are problematic, please let me know.

   3. Missing reference in "1.2 Relationship to DAV" Is it DAV or
   WebDAV?

Depends who you ask ... I know Greg likes DAV and JimW prefers
WebDAV.  But the document should be consistent.  I prefer to keep
DAV as the namespace, and WebDAV as the name of the working group
and the protocol, so I've tried to consistently use WebDAV (but
missed this obvious place ... thanks for pointing it out!).

   Was the idea to hide the clarifications to RFC 2518 or just
   to remove them?

Just a gotcha from the Word update references command.  It got
moved and Word couldn't find it's new location. 

   In any case, now that there's no longer a set of
   clarifications, maybe all of 1.2 should go.

There still is the one clarification of the COPY request, so
I'll keep the pointer to that here.

   4. Section 1.3 Notational Conventions This is an odd place to put
     this, since some of these conventions are used in previous
     sections.

Yes, another reviewer pointed that out as well.  The section has been
moved earlier, to avoid the use before definition problem.

     Since RFC 2068 has been obsoleted, it is odd to use
     that as a source of BNF syntax and BNF production rules; In the
     updates from 2068 to 2616 we may have fixed errors in the BNF.

Actually, there was only one trivial use of BNF left in the document,
so I just got rid of that, and then we can get rid of the reference
to 2068 altogether.

   5. Sec 1.3 "When a precondition or a postcondition of a method is
   defined in this document, it can be prefixed by a parenthesized XML
   element type." It's not clear what it is that can be prefixed: the
   precondition, the postcondition, the method, or the definition. I
   think you mean 'the definition can be prefixed', or, rather, 'when
   the definition is prefixed, this means'.  This notational
   convention may have saved you a few keystrokes, but a little bit of
   elaboration in place would allow you to remove this confusing bit
   of notational convention.

I can certainly replace the "it" with "the definition" to avoid any
confusion here.  What in place elaboration did you have in mind?

   6. 1.4 Terminology

   The entire terminology section is pretty confusing; terms are
   defined circularly or else make reference to other terms that are
   not themselves defined.

There will always be some level of circularity in a definition
section, but I have tried very hard to minimize the forward references.
You make some very good suggestions below, which I will act on.
Certainly there's no reason to have undefined terms!

   I think that it might be possible to put
   together a "model" that describes the relationship between
   resources, versionable resources and versions that would help a
   lot, and putting forward references to the places in the actual
   protocol that use the terms will help with anyone trying to figure
   out what this stuff really means.   Some of the terms apply in
   general (whether or not resources are version-controlled) and
   others are versioning specific.

There is a model for these terms in the core versioning semantics
section (and even some beautiful ascii art :-).  I'll add
a forward reference to this section from the terminology,
so that a reader does not mistakenly believe that they should
be able to infer the versioning model from the terminology
section.  But the terms themselves are used in hundreds of
locations throughout the protocol, so I believe a forward reference
from the terms to each of their uses would not end up being
very helpful (maybe that's not what you were suggesting?).

   Specific comments below:

   7. Core Versioning As above: this term needs a real definition. I
   think it's a "conformance level" but I'm not sure what it is or
   whether it's actually a formal term. Each property and method
   carries its own conformance requirement.

Good point.  Core versioning should be defined as "what is in
section xxx".

   7. Terms/Versionable Resouce: "Put under version control" This
   phrase is used to define other terms, but it is not itself
   defined. Maybe what's needed is a model that places these terms in
   some context?

I think "version control" needs to be a defined term.  I'll add one.

   8. 1.4 Terms/Version-controlled resource "A version-controlled
   resource can be "checked out" to allow modification of its ..."  Is
   the resource modified, or a version modified?

I believe the "it" is unambiguous, since there is only one noun
in the sentence (i.e. "version-controlled resource").  Could
you expand a bit on what was ambiguous (I didn't see any reference
to a "version" in this definition).

   The phrase "put under
   version control" isn't defined; what action puts something under
   version control?

We haven't yet defined any of the methods, and were trying to avoid
doing so in the terminology section.  But I agree that "version control"
needs to be a defined term, and I hope that will clarify this statement?

   9. 1.4 Terms/Version Resource The term is "Version Resource" but
   the paragraph defines "Version".

I'll fix that.  In many cases, "xxx resource" can be abbreviated
to be just "xxx" (e.g. version, activity, workspace), but this should
be stated explicitly when the term is defined, not left to the
reader to guess.

   Is there no version of a
   version-controlled resource before the first check-in, or is the
   fact that a version is created by checking in a checked-out
   resource just an example.

That should be clear after you've read the versioning model
section.  If it is not, please let me know.  (Without a
forward reference to the model, I agree this definition
is confusing).

   The definition talks about what the
   server must do with URLs, but perhaps this bit of conformance
   requirements belongs somewhere else, in a section that describes
   what conformant servers MUST and MUST NOT do.  Right now, in the
   'terms' section, you're just defining terminology.

I agree.  This requirement is actually repeated later, so there is
no reason to have it here.  I'll get rid of all MUSTs from the
terminology section.

   10. Section 1.4.1 "Optional Versioning Terms"

   I think what you mean to say is these terms are only needed by the
   "Optional methods" and not by the "Core versioning" definitions. So
   it's "(Optional Versioning) Terms" rather than "Optional
   (Versioning Terms)".  Why is this 1.4.1 instead of making "Terms
   for Core Versioning" section 1.4.1 and making section 1.4.2 "Terms
   for Versioning Options"?

I agree.  I'll rename it, and move it forward to a "versioning options"
section, so that it doesn't make core look more complicated than it
needs to be.

   11. 1.4.1 / Working Resource

   Do you check out a "version" or a "version resource" or a
   "version-controlled resource"? Earlier, it seemed like it was a
   "version-controlled resource" was the target of "check out". Maybe
   the term "check out" needs to be defined?

This is intentionally left open (although the ambiguity between
version and version needs to be cleared up by explicitly stating
that "version" is just a shorthand for "version resource").

But to avoid confusion, I agree that "checked-out" and "checked-in"
need to be explicitly defined.  

In core versioning, a version-controlled resource can be checked
out.  In the checkout option, a version-controlled resource can
be the target of an explicit CHECKOUT request.  In the working
resource option, a version resource can be the target of an explicit
CHECKOUT request.

   12. 1.4.1 Workspace Resource The title is "Workspace Resource" but
   the term defined is "Workspace". Which is it?

Same problem as before.  They are synonyms.  I'll make this explicit.

   Must a Workspace
   Resource have at least one version-controlled resource and at least
   one non-version-controlled resource? Why?

No it doesn't, but I can see why the current phrasing would lead you
to think this.  I'll fix this.

  "A workspace MUST NOT
   contain two different version-controlled resource for the same
   version history." I don't think it's well-defined what "the same
   version history" means. It's not clear whether this is a constraint
   on clients or on servers or just a general expectation.

Good point.  I'll put a forward reference from each version options
term to the option that defines it.  This should make it clear where
to look to answer a question like this.

   13. "Version-Controlled Collection Resouce"

   This term is defined by reference to the phrase "collection that is
   under version control" but there's no definition anywhere of what
   it means for a collection to be "under version control" (except,
   perhaps, circularly, that it is a version-controlled collection
   resource).

Yes, the term "version control" definitely needs to be defined, so
that when it is used, it is not confusing.

   14. "Collection Version Resource"

   This also seems to define "A version-controlled binding"; it
   defines it as a binding to a version-controlled resource, but it's
   not clear if this is the binding to the checked-in version or
   something else.

The versioning model section should clear this up, since it
emphasizes that a version-controlled resource is a very different
thing from a version resource, so a binding to a version-controlled
resource is very different from a binding to a version resource.
(Note: A version-controlled binding is as defined, namely to a
version-controlled resource, not to a version resource).

And thanks again to Dan (and his scribe, Larry :-) for this great
review!  I look forward to getting the rest of it.

Cheers,
Geoff

Received on Monday, 12 February 2001 07:21:07 UTC