Next message: Eric Sedlar: "Re: Auto version for workspaces"
From: Jim Whitehead <ejw@ics.uci.edu>
To: ietf-dav-versioning@w3.org
Date: Wed, 16 Feb 2000 15:09:46 -0800
Message-ID: <NDBBIKLAGLCOPGKGADOJKEDFCOAA.ejw@ics.uci.edu>
Subject: Comments on versioning-03
Well, I've read through the spec. up through the end of Section 7, and
wanted to send my comments out.
* Introduction. I think it would be really helpful to have a roadmap of the
spec. at the end of the introduction, especially since there is a major
organizational theme of having the basic versioning first, followed by the
advanced versioning (BTW, so far, I'm liking this split). Section numbers
can be left as TBDs, but readers at this point should be made aware of the
basic/advanced split.
* Definition of revision: A "revision" of a versioned resource is *a* write
protected...
* Definition of workspace: In my mind, this definition doesn't really
capture the essence of what a workspace is. A workspace is used to create
separate, isolated work areas for individuals or groups to work within.
That is never said. As the definition now stands, it says a workspace is a
string, and "workspace" is a pretty loaded term just for a string :-)
* Definition of target: I think this definition, or someplace in the spec.,
needs to provide some explanation as to why we're always working on the
target. The basic reason is that we want to preserve the pre-versioning URL
namespace for operations when the resources are now under version control
(for correct handling of relative URLs, among other reasons). Since there
are many revisions, we need to map the multiple revisions into the one
single pre-versioning URL.
* Notational conventions: This spec. actually does introduce some new
notational conventions above and beyond those defined in WebDAV and HTTP,
specifically the "(protected)", "<Activity>", "<Versioned-Collection>", and
"(readonly)" tags that appear in section headings. What do these all mean
(and are they somehow normative)? It's never explained.
* Section 2.2, "Naming Working Resources": I think this text might be more
clear if we distinguish between the workspace abstraction (an isolated work
area for a person or workgroup) and a workspace identifier (the string).
* Section 2.3, third paragraph: I'd like to recommend the paragraph begin
with the sentence: "Revision identifiers and revision labels are unique only
across a single versioned resource. That is, a revision id or revision
label...."
* Section 3.1.5, stable-href: I really don't see any value in introducing
this, and it causes problems. For example, the way that it is used in
ELEMENT definitions in DTD language is not right. For example:
<!ELEMENT initial-revision (stable-href)>
This indicates there is an XML element called stable-href. But, the
definition of stable-href is that it is just an HREF element, thus implying
that stable-href is some kind of macro-substitution. But, in XML
processing, there is no preprocessor, and so this kind of substitution isn't
allowed. There are XML macro facilities, but I really don't think they're
called for here. Just use href.
* What does "(protected)" mean in a section heading (e.g., section 3.3.1).
It's never defined.
* The auto-version semantics described in section 3.3.4 really need to be
pulled-out of the property description, and placed in a separate section.
There are a lot of subtle issues that need to be dealt with for
auto-versioning (like, error handling -- what happens if the automatic
CHECKOUT succeeds, but the PUT fails?), and having a separate section will
allow them to be better addressed.
* DAV:revision property. I think having a DAV:revision and a DAV:revisions
(plural) property is just asking for trouble. Let's call DAV:revision
something like DAV:revision-href instead.
* 3.4.5, DAV:labels. Any string that appears in the protocol that is
displayed to the user MUST be internationalized, or you violate IETF i18n
policy. Since this section states that revision labels are exposed to the
user, then the strings must be tagged with language, and charset.
* 3.4.6 DAV:checkin-date: This needs to state that it is the time,
according to the versioned resource (that is, the origin server), and not
according to the client.
* 3.4.7 DAV:workspaces. Wording suggestion. "This property identifies the
workspace for the working-resources derived from this revision (i.e., whose
DAV:predecessors..."
* Section 3.4.9 DAV:versioned-resource. Wording suggestion. "This property
identifies the versioned resource that contains this revision (i.e., whose
DAV:revisions..."
* Section 5.1: MKRESOURCE should return a 201 (Created) when it successfully
creates a new resource, instead of 200 OK.
* Section 5.2: This section should describe at a high level what each of the
reports provides, and should also have forward references to the sections
(specifically, section 12) that define each of the reports, if they're not
defined in section 5.2 I couldn't find any description of the lock report,
and I recommend deleting it. Towards the end of Section 5.2, there is a
cut-and-paste error: "The following status codes are used to transmit
*REPORT* results..."
* Section 5.4, Property report. Those are some pretty funky semantics for
the property report. I'm starting to think it might just be better to have
specific reports, rather than this general, albeit funky, mechanism. I
could be convinced otherwise, though. But, the spec. would need much
stronger rationale to convince me (or any other reader, I imagine).
* Section 6.1, VERSION. The list of postconditions doesn't list the values
of all the properties that are set on the versioned resource and on the
initial revision. I'd expect a list that contains just about every property
from section 3.3 and 3.4, explaining what its value will be at the end of
the method's execution.
* Section 6.1.1. The example can drop the Content-type headers, but needs to
add the Host header and the Request-URI needs to have the scheme, and
hostname removed to be HTTP/1.1 compliant (this was mentioned during a
previous teleconference).
* Section 6.2. In the postconditions, the property is DAV:predecessors
(plural) rather than DAV:predecessor.
* Section 6.2. I think there needs to be another status code, 4xx (Already
Checked Out).
* Section 6.2.1. The example needs a Content-Length header in the response.
The request does not need a Content-type header.
* Section 6.4, CHECKIN. Same as for VERSION, the effect on properties needs
to be better described. For example, DAV:checkin-date needs to be set, as
does DAV:versioned-resource.
* Section 7.1: The terminal Workspace-URL is never defined.
* Section 7.2: The BNF and the examples disagree. If the example is
correct, then the BNF needs to have quote characters around the "segments".
That's all for now...
- Jim