Next message: Tim Ellison OTT: "Re: Labels"
Message-ID: <65B141FB11CCD211825700A0C9D609BC01FA6038@chef.lex.rational.com>
From: "Clemm, Geoff" <gclemm@Rational.Com>
To: ietf-dav-versioning@w3.org
Date: Wed, 23 Feb 2000 00:06:57 -0500
Subject: RE: Comments on versioning-03
> From: Jim Whitehead [mailto:ejw@ics.uci.edu]
>
> * 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.
I've added some words along these lines. Let me know if they are
sufficient.
> * Definition of revision: A "revision" of a versioned
> resource is *a* write
> protected...
Done.
> * 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 :-)
This is done to provide compatibility between basic and advanced
versioning. In advanced versioning, where a workspace is a resource,
the definition is as you describe. In basic versioning, the proposal
is that a workspace just be a server defined string that is used
to identify one working resource of a versioned resource
from another working resource of that versioned
resource (i.e. a checkout token). A workspace identifies a working
resource in both basic and advanced versioning. It is "reified" as
a resource in advanced versioning, at which time it provides the
more sophisticated functionality that we commonly associate with the
term "workspace".
> * 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.
I added the sentence:
"This allows a client to largely ignore the fact that a resource has been
placed under version control."
Let me know if you'd like more (and what exactly you'd like it to say :-).
> * 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.
I added a description of "(protected)" to the notational conventions
section. The angle bracket terminology was a remnant of not
separating the document into "basic" and "advanced". With the
document separated, I'll just delete these annotations (they were
really too coarse-grained anyway, since a server could implement
only part of one of these "categories", e.g. could implement
configurations but not activities, or vica versa).
> * 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).
The proposal is that only the use of a workspace to identify a
working resource appear in basic versioning, so there is no need
to discuss the workspace abstraction until advanced versioning.
> * 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...."
Done.
> * 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.
It is important for clients and servers to know which properties
contain stable href's, but I agree that it doesn't require its own
XML element. I'll just move the "stable" descriptor into the body
of the property definition.
> * What does "(protected)" mean in a section heading (e.g.,
> section 3.3.1).
> It's never defined.
It means that the property cannot be modified by a PROPPATCH.
I've added this definition in the "Notational Conventions" section.
> * 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.
There is such a section (paragraph 2 of section 4: Versioning and
Existing methods). I'll give it its own title to highlight this
feature. This section does need to be expanded to handle the
error conditions (after we figure out what those error conditions
are :-). I'll add this to the "Open Issues" section.
> * 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.
We also have a DAV:activities, DAV:versioned-resources, and
DAV:workspaces. Does this mean we want DAV:activity to be
DAV:activity-href, DAV:versioned-resource to be
DAV:versioned-resource-href, and DAV:workspace to be
DAV:workspace-href? What about when something that used to only
have a singular form gets a plural form? If you really think this
is an issue, I'd probably go the other way, and change the plural
to be DAV:revision-set, DAV:activity-set, etc. Tim: This means
you will need to update the scenario document with the new
property names (for which you can thank Jim ... :-).
> * 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.
I agree with those on the mailing list who have argued that it is
sufficient to internationalize labels to the extent that URL's are
internationalized, which does not include tagging 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.
Since this is a protected property (i.e. set by the server), this
issue should not arise.
> * 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..."
Done.
> * Section 3.4.9 DAV:versioned-resource. Wording suggestion.
> "This property
> identifies the versioned resource that contains this revision
> (i.e., whose
> DAV:revisions..."
Done.
> * Section 5.1: MKRESOURCE should return a 201 (Created) when
> it successfully
> creates a new resource, instead of 200 OK.
Done.
> * 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 can see putting in a forward reference to section 12, but why
would we want a high level definition of what each of the reports
provide? Wouldn't it just needlessly confuse readers that are only
interested in basic versioning, while those interested in advanced
versioning could skip ahead to section 12?
> I couldn't find any description of
> the lock report,
> and I recommend deleting it.
Done.
> Towards the end of Section 5.2,
> there is a
> cut-and-paste error: "The following status codes are used to transmit
> *REPORT* results..."
Done.
> * 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).
We'd have to have a combinatorially explosive number of individual
reports to cover any reasonable set of client scenarios, so I'm
strongly against that, but I agree that this report needs to be
both motivated and exemplified (not what the dictionary would define
"exemplify" to be, but you can probably guess what I mean :-).
> * 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.
Yeah, I just stuck this in at the last minute to match up with
the scenario document. I'll add this to the To-Do section.
> * 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).
Done.
> * Section 6.2. In the postconditions, the property is DAV:predecessors
> (plural) rather than DAV:predecessor.
Done.
> * Section 6.2. I think there needs to be another status
> code, 4xx (Already
> Checked Out).
Currently this is a 409. We would like to give additional
information. Like Yaron, I'd rather put this in some extensible
XML value, rather than enumerating the set of "interesting"
cases of the 409. But like Jim, I'm hesitant about biting off
this issue in the versioning protocol. So I'm inclined to just
keep it as a 409, and require that the client query the state
on the server to see what went wrong.
> * Section 6.2.1. The example needs a Content-Length header in
> the response.
> The request does not need a Content-type header.
Done.
> * 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.
Yes. I'll add this to the ToDo section.
> * Section 7.1: The terminal Workspace-URL is never defined.
Done.
> * 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".
Done (got rid of the quote characters).
> That's all for now...
Thanks, Jim !!
I'll post a new working draft of the spec based on Jim's comments to
the usual locations (hopefully, tomorrow).
Cheers,
Geoff