- From: Tim Ellison <tim@peir.com>
- Date: Wed, 17 Jan 2001 12:06:44 -0500
- To: <ietf-dav-versioning@w3.org>
[freed from spam trap -rrs[
Date: Wed, 17 Jan 2001 12:03:21 -0500 (EST)
Message-ID: <004b01c0808f$400434b0$27181409@hursley.ibm.com>
From: "Tim Ellison" <tim@peir.com>
To: <ietf-dav-versioning@w3.org>
I had a thorough read through 11.1 and as I indicated in my earlier message
had no significant changes.
I'll post these to the list, but they are really only of interest to the
authors as they are small editorial changes.
I'm sure Geoff will call-out anything that requires wider discussion.
Roll-on Friday!
Tim
--------
General beefs:
There are a number of places where the text says a property must contain
a version etc. when it means that the property must "contain the URL of" a
version etc.
In the 'OPTIONS Additional Marshalling' sections there are DTDs for the
request and the response without any indication of which is which. Either
some text, or a subheading would be useful.
Trivia:
(Nothing of any significance here, just some things that I thought would add
a little more clarity or questions that came to mind as I was reading
through the document.)
Authors list
Check Jim Whitehead's affiliation
1.3 Terms
'This draft' --> 'This document'
'A "version history" is a resource that contains all the versions ...'
consider '... that references all the versions ...'
'Root Version Resource'
consider renaming the term 'Initial Version Resource' as the term root
is used elsewhere in the document, as in a root collection.
1.5.2 Property Value Locking
This section is too general as it can be read to mean that requests
whose side-effects are a modification of another resource's (computed)
property MUST include the lock token of any resources that they affect. I
do not believe that this is the intent.
2.1.1 Creating a Version-Controlled Resource
para. 1 '... and creates a version in this version history...'
consider '...of this version history...' (that 'contains' thing again)
para. 3 '... the resource that is now under version control.'
consider '... under version control (the 'version-controlled resource).'
for clarification and definition of the term.
2.1.2 Modifying a Version-Controlled Resource
para. 2 '... with the DAV:auto-version property set'
I'm assuming that this has been rewritten based on the value of the
property.
2.2.1 DAV:checked-in
'This URL can be used to retrieve this particular state of the
version-controlled resource after the version-controlled resource itself has
been modified.'
Given that this is a property of a checked-in version-controlled
resource, I fail to see how the version-controlled resource itself can be
modified.
2.2.3 DAV:predecessor-set
Should state that the predecessors MUST be part of the same history.
2.2.4 DAV:precursor-set
Should state that the predecessors MUST NOT be part of the same history.
Why are we required to make this distinction between predecessors and
precursors?
2.2.5 DAV:auto-version
Assuming that the vallue of the property is being defined rather than
saying it is set.
As it reads now, having it set to 'false' would cause auto-versioning to
take place.
Maybe clarify what happens when a write lock expires, presumably the
checkin attempt occurs, and errors are never reported to any client.
2.3.5 DAV:checkin-date
'This property contains the date on the server when the version was
checked in.'
Consider '..when the version was created.' since the initial version is
not checked in.
2.5 DAV:version-tree REPORT
Marshalling:
'...with at most one a DAV:prop...' -> '..with at most one DAV:prop...'
<!ELEMENT version-tree (href, prop, version-tree*)
Why DAV:prop and not DAV:propstat? -- what about requests for
non-existant properties?
Why are the DAV:version-tree elements nested? It does not convey "true"
structure, especially since 'A server MAY omit the DAV:prop and the
successor DAV:version-tree elements ...' I don't see that the nesting is
helpful.
2.5.1 Example - DAV:version-tree-report
>>REQUEST
Last line of the XML has a gratuitous xmlns definition.
2.7 Additional PUT semantics
(DAV:cannot-modify-version-controlled-content) &
(DAV:auto-checkout)
Assume that the DAV:auto-version consideration is being re-written.
(DAV:auto-checkout-checkin)
Uses the obsolete term 'revision' twice.
2.8 Additional PROPPATCH semantics
(DAV:cannot-modify-computed-property)
Consider removing this precondition and stating (earlier) that all
computed properties are protected.
(DAV:auto-checkout) &
(DAV:auto-checkout-checkin)
Assume that the DAV:auto-version consideration is being re-written.
(DAV:auto-checkout-checkin)
Uses the obsolete term 'revision' twice.
2.9 Additional DELETE semantics
(DAV:cannot-delete-root-version)
Why? Consider that the value of DAV:root-version becomes undefined on
its deletion.
(DAV:no-version-delete)
Reads more like a precondition.
(DAV:update-predecessor-set)
I presume this is to prevent "holes" in the history, but this won't work
in the face of merges.
2.10 Additional COPY semantics
(DAV:auto-checkout)
Assume that the DAV:auto-version consideration is being re-written.
Uses the obsolete term 'revision' twice.
3.1 CHECKOUT Method
What happened to the text that stated a lock token is required if the
resource is write locked?
3.2 CHECKIN Method
(DAV:initialize-version-content-and-properties)
'The DAV:checkin-date of the new version MUST be set...'
Should state where possible to be consistent with definition of property
(2.3.5).
4.1 UPDATE Method
Marshalling:
'...with at most one DAV:version element.'
So what would zero elements mean?
(DAV:must-select-version)
Consider renaming (DAV:must-select-version-in-same-version-history)
4.1.1 Example - UPDATE
'In this example, the content and dead properties of http://... are
copied to the vesion-controlled resource /foo.html, ...'
Consider 'In this example, the version-controlled resource /foo.html is
updated with the content and dead properties of http://...,'
5.1.2 DAV:root-version
Consider renaming to DAV:initial-version
5.2.1 DAV:version-history
Consider changing from (computed) to (protected).
Consider defining in terms of DAV:version-set (5.1.1).
5.4 Additional OPTIONS Semantics
Is it required that the history for the resource reporting the OPTIONS
MUST be in the version-history-collection-set? Probably unnecessary since
clients can get to the history via properties.
Consider an example.
6.1 Working Resource Properties
'The server allocates a distinct new URL for each new working resource.'
What does this imply? That the server cannot reuse working resource
URLs once the working resource has been checked in or deleted?
6.3 Additional COPY semantics
'...a new non-version-controlled resource at the destination...'
consider adding 'with the same content and dead properties...' as
written elsewhere in the document.
6.5 Additional CHECKOUT Semantics
Additional Marshalling:
'The response MAY include a Location header.'
How else would you find a working resource URL? Consider MUST.
6.6 Additional CHECKIN Semantics
'...new version whose contents and dead properties are those of the
working resource.'
consider '...and dead properties are the same as those of the..'
(DAV:delete-working-resource)
'...if DAV:keep-checked-out is not specified, the'
consider '...is not specified in the request body'
(there are a number of places where it is confusing as to whether the
element name given in text is a property name or an element in the request
body.
7 Server-Workspace Option
para. 4
Unless the URLs are relative, the workspace name will get in the way of
testing.
7.2 Additional Resource Properties
'...for an HTTP resource.' --> 'for a WebDAV resource.' (it has to
support properties<g>).
7.2.1 DAV:workspace
'The DAV:workspace property of any other type of resource MUST be the
same as the DAV:workspace of its parent collection.'
But only when the immediate parent collection defines a workspace.
7.3 DAV:version-controlled-resource-url REPORT
Consider moving this section after 7.4 MKWORKSPACE Method.
Marshalling:
'The DAV:version-controlled-resource REPORT response body MUST be a
DAV:version-controlled-resource XML element' --> 'The
DAV:version-controlled-resource-url ...be a
DAV:version-controlled-resource-url ...' (two corrections)
What happens if the version-controlled resouce was deleted?
7.3.1 Example - DAV:version-controlled-resource-url REPORT
>> RESPONSE
xmlns definition should be moved out a level.
7.4 MKWORKSPACE Method
(DAV:workspace-location-ok)
Consider renaming to (DAV:workspace-lcoation-not-OK)
[All other OK's have been caps. ;-]
(DAV:initialize-workspace-properties)
'The DAV:resource type...' --> 'The DAV:resourcetype...'
(DAV:initialize-workspace-properties)
'The DAV:workspace of the workspace MUST contain the request-URL.'
consider 'The DAV:workspace property of the workspace MUST identify the
new workspace.' i.e., let servers put some alias in there if they choose.
7.5 Additional OPTIONS Semantics
para.2
'If a server support the ...' --> 'If a server supports the ...'
Additional Marshalling:
How would a server indicate that workspaces can be created anywhere? or
here and below?
7.7 Additional VERSION-CONTROL Semantics
(DAV:one-version-controlled-resource-per-history-per-workspace)
'...there MUST NOT already be a version-controlled member of that
workspace ... identifies a different version from the version history...'
consider ' ... identifies any version from the version history...'
(DAV:version-controlled-resource)
'...whose content and dead properties are initialized by those of...'
consider '...are the same as those of...'
7.7.1 Example VERSION-CONTROL ...
'...the content and deap properties ... are those of the version...'
consider '...are the samae as those of...'
8.2 MERGE Method
Marshalling:
'<!ELEMENT merge ANY>'
'..., and at most one of any element that can occur in a DAV:checkout
element.'
This is too restrictive for future extensions, consider '..., and any
legal set of elements that can occur...'
(DAV:update-merge-set)
'...and if DAV:checked-out version...' --> '..and if the DAV:checked-out
version...'
Final two postconditions of this method do not have any advanced status
element defined.
8.3 DAV:merge-preview REPORT
'<!ELEMENT merge-preview (update-preview-set, merge-preview-set,
ignore-preview-set)>'
Consider adding a '*' so that servers can generate these sets of XML on
the fly rather than having to compute the entire set of each before
responding.
9 Label Option
para. 2
consider a forward reference to 9.3 Label Header
para. 3
consider striking this paragraph -- although an interesting footnote it
doesn't add anything and may even imply permission to create duplicate
labels.
9.2.1 Example - Setting a label
>>Request
Why the change of XML layout?
9.8 Additional CHECKOUT Semantics
postconditions
'If a version-controlled resource was checked out, ... the
version-controlled resource MUST remain checked in.'
Huh??
9.9 Additional UPDATE Semantics
Presumably the response is Bad Request if a client attempts to specify a
contradictory Label and <DAV:apply-to-version/>.
10 Baseline Option
The ascii art added nothing for me, consider striking it.
10.1.1 DAV:baseline-controlled-collection
Consider (computed) -> (protected)
10.2.2 DAV:subbaseline-set
'...a set of other baseline.' --> '...a set of other baselines.'
10.4 BASELINE-CONTROL Method
Consider adding some descriptive text regarding creating a new baseline
selector on an existing baseline.
(DAV:must-have-no-version-controlled-members)
Hmm, don't get why this one is required.
postconditions:
Consider each occurrence of 'the collection' --> 'the target collection'
(DAV:select-existing-baseline)
'...each version in the baseline, where the version-controlled
member...'
consider '...the baseline, and the ...'
10.5 DAV:baseline-comparison REPORT
Marshalling:
Why are the results not reported as sets in keeping with the other
reports that respond with multiple URLs.
Postconditions:
This section still seems to be referring to marshalling rather than
postconditions (of the repository) of the method as in other postcondition
sections.
10.7 Additional OPTIONS Semantics
Additional Preconditions:
'... the response body MUST contain a
DAV:baseline-controlled-collection-set element identifying which collections
are under baseline control.'
Eek, why would a client want this "global" information? I think this is
too difficult to require all servers to supply, and will potentially make
the OPTIONS request very expensive (IMHO clients presently consider OPTIONS
to be cheap and send them frequently.)
10.10 Additional CHECKIN Semantics
(DAV:create-baseline-version-set)
'...the DAV:baseline-version-set of the new baseline contains the ...'
consider '... of the new baseline version contains the ...'
10.11 Additional UPDATE Semantics
(DAV:set-baseline-controlled-collection-members) last bullet point
'An UPDATE request MUST have been applied to each version-controlled
member whose DAV:checkin-set does not identify a version in the
DAV:baseline-version-set of the baseline.'
consider '... whose DAV:checkin-set does not identify the same version
...'
10.12 Additional MERGE Semantics
'If the merge version is a baseline, the merge target is a baseline
selector for the baseline history of that baseline, where the
baseline-controlled collection of that baseline selector is a member of the
merge destination of the request.'
That deserves an award for the greatest use of the word 'baseline' in
one sentence. Just read it very slowly.
11 Activity option
para. 3
'Activity semantics then ensures that ...' --> 'Activity semantics then
ensure that ...'
11.2.1 DAV:activity-set
'...indicate to which logical changes this activity contributes, and on
what lines of descent this version appears.'
Surely '.. this version contributes...'
what does 'and on what lines of descent this version appears.' mean?
11.3.1 DAV:unreserved
all instances of 'checked-out resource' should read 'checked-out
version-controlled resource'.
para. 2
'... merge the latest version of that activity...'
consider '... of the version-controlled resource in that activity...'
11.3.2 DAV:activity-set
'...checked-out resource...' --> '...checked-out version-controlled
resource...'
Why not allow this property on checked-in and checked-out resources as a
convenience? Just an idea.
11.5 MKACTIVITY Method
(DAV:activity-lcoation-ok)
consider renaming to (DAV:activity-location-not-OK)
(DAV:create-activity) &
(DAV:initialize-activity-properties)
The corresponding postconditions for MKWORKSPACE do not distinguish
these as separate advances status codes, this should be consistent.
11.7 Additional OPTIONS Semantics
'An activity collection MAY be the root collection of a tree of
collections, all of which may contain activities.'
I propose that this is true of all OPTIONS reported locations (e.g.,
DAV:workspace-collection-set)
11.10 Additional CHECKOUT Semantics
Additional Preconditions: (both)
'If there is a request activity set, ...'
consider clarifying with 'If the request body contains a
DAV:activity-set element,...'
11.10.1
>>RESPONSE
Does not contain a cache conrol header as required per 3.1.
11.11 Additional CHECKIN Semantics
(DAV:linear-activity)
An example of a '...resource MUST be in the DAV:predecessor-set...'
(DAV:initialize-activity-version-set)
An example of a '...URL for the new version is added to the
DAV:activity-version-set...'
Should be consistent about describing resources added to properties or
URLs added to properties, otherwise the reader may think you are referring
to differerent things.
11.(13?)
Shouldn't there be Additional UNCHECKOUT Semantics to remove the
checked-out version-controlled resource URL from a
DAV:activity-checkout-set? If so, this is likely true for more methods that
have additional CHECKIN/CHECKOUT semantics.
12.4 Additional PUT Semantics
I know that I've been banging this drum for 12+ months. but I don't like
the idea of <version URL>/member URLs.
12.9 Additional CHECKIN Semantics
(DAV:no-eclipsed-baseline-controlled-collection-members)
I don't understand the rationale for this precondition.
13.1.1 DAV:checkout-fork
'<!ELEMENT checkout-fork (ok | discouraged | forbidden )>'
Consider using ANY for future extensions.
13.1.2 DAV:checkin-fork
'<!ELEMENT checkin-fork (ok | discouraged | forbidden )>'
Consider using ANY for future extensions.
22 Authors' Addresses
Check Jim W's contact details.
23.1.1 DAV:comment
Why do we have an extra DAV:string element?
Why can you have any number of them (how would a client choose which one
to display)?
23.2 Response Bodies ...
para. 2
'...each method precondition defined in this document...' -->
'...each method precondition and postcondition defined in this
document...'
Should mention the purpose of the postcondition stati.
'...the appropriate XML element MUST be returned in the response
body.' -->
'... in the response body unless otherwise negotiated by the request.'
23.3 Clarification of COPY ...
para. 4.
'Roy Fielding (an author..'
consider striking this paragraph (and moving it to the book of why)
23.4 REPORT Method
Marshalling:
'The request body of a REPORT request...' -->
'The body of a REPORT request...'
Minutae:
(This stuff is way below trivia, but caught my eye when reading the
document. I'm almost embarrassed to send these in.)
Abstract
Add comma after 'URL namespace versioning'
2.10 Additional COPY semantics
Extra space before the text '(DAV:initialize-precursor)'
5.8 Additional VERSION-CONTROL Semantics
(DAV:new-version-history)
double space in '..for that version history that MUST NOT...'
5.9 Additional CHECKIN Semantics
(DAV:preserve-version-history)
the document already uses (DAV:preserve-history) consider consistent
naming.
8.2 MERGE method
para. 2
double space in '...the DAV:auto-merge-set property of the...'
10.11 Additional UPDATE Semantics
(DAV:set-baseline-controlled-collection-members)
double space in '... identifies a baseline, then the
version-controlled...'
11.11 Additional CHECKIN Semantics
(DAV:linear-activity)
double space in '...the DAV:predecessor-set of the checked...'
23.5.1 Example - DAV:property-report
>>REQUEST
last three lines have extra space '</D:property >' -->
'</D:property>'
Received on Wednesday, 17 January 2001 12:07:46 UTC