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

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.

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. However, it is often the case that
confusing or ambiguous wording hides errors in protocols. 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".

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. 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.

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.

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."

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.

3. Missing reference in "1.2 Relationship to DAV"
Is it DAV or WebDAV? Was the idea to hide the clarifications to
RFC 2518 or just to remove them? In any case, now that there's no
longer a set of clarifications, maybe all of 1.2 should go.

4. Section 1.3 Notational Conventions
  This is an odd place to put this, since some of these conventions
are used in previous sections. 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.

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.


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. 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.

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.

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?

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? The phrase "put under
version control" isn't defined; what action puts something under
version control?

9. 1.4 Terms/Version Resource
The term is "Version Resource" but the paragraph defines "Version".
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.  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.


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"?

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?

12. 1.4.1 Workspace Resource
The title is "Workspace Resource" but the term defined is "Workspace". Which
is it? Must a Workspace Resource have at least one version-controlled
resource and at least one non-version-controlled resource? Why?
"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.

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).

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.

Received on Saturday, 10 February 2001 17:30:32 UTC