Versioning Protocol 2.2 Review

jamsden@us.ibm.com
Fri, 8 Oct 1999 14:14:27 -0400 

From: jamsden@us.ibm.com
To: ietf-dav-versioning@w3.org
Message-ID: <85256804.0064355F.00@d54mta03.raleigh.ibm.com>
Date: Fri, 8 Oct 1999 14:14:27 -0400
Subject: Versioning Protocol 2.2 Review



Here's my comments on version 2.2 of the versioning specification.

Section 1.2 :

The last sentence of the definition of a baselined collection contains a
circular definition. It should read "A baseline is a configuration that contains
a revision of the associated versioned collection and a revision of each and
every member of that versioned collection with depth infinity."

For the definition of history resource, my notes from concord say: Decide on a
name for the versioned resource as a whole, currently called a history resource.
Use the new name in the *-id property names. Resolution: use resource, revision,
and versioned resource instead of versioned resource, revision, history
resource. In cases where it the resource must be a revision, note it.

2.4, last sentence: merge operation is not defined.

2.7 needs an example.

3.1.3 Property Resources: WebDAV already has properties that are references to
resources. For example DAV:link and DAV:href. It seems confusing to have
PROPFIND follow these links for some references and not others, and to require a
special header DAV:property-resource-URL to get the actual value of the
property. I have no problem representing properties as references to resources,
just this optimization seems a little contrived.

Section 2 needs examples of methods that perform the functions described in each
section. This ties the methods, headers, entity bodies, properties, and new
resource types back to the semantics.

3.2.1 implies that the DAV:rev element is a list of revision identifiers when
what is meant is that the rev element is used as an entry in such a list.

3.2.2 revision labels also appear in headers which cannot use XML encodings.

3.2.3 WebDAV uses "T" and "F" fro boolean values. See DAV:overwrite.

3.3.2 ELEMENT comment not author

3.4.6 says  the DAV:auto-version value can take the same values as the
DAV:checkin-policy, but the value is described and given as boolean.

3.4.6 revision-labels could be just labels

3.4.9 is DAV:history-uuid the same as requesting the DAV:history property with
DAV:property-resource-URL?

3.4.12 DAV:merge-successors is defined to contain bindings to each revision. All
the other predecessor/successor properties use less specific language. The XML
document contains revision-ids, not bindings. Perhaps the use of bindings in
this context is incorrect or misleading.

3.4 Missing DAV:activity for Revision resources.

3.5.3 DAV:baseline doesn't make sense. The checkin must be done and followed by
a make baseline. This seems like an excess of control coupling. Why is this
policy needed? Isn't it the same as checkin followed by make baseline?

DAV:checkin-policy is not extensible as written. Need to add ANY? Should
checkin-policy be a client responsibility? DAV:baseline cannot be part of
[Core].

3.6.1 Need a definition of the XML document for DAV:working-resources property.

3.6.2 ..., thus target... .... The target... I thought RSRs were part of
"extended" workspace semantics and weren't part of [Core] (although I don't
necessarily agree with this). Where is the RSR defined?

3.7.2 DAV:needed-activities should be required-activities.

3.7.3 Why is it necessary to restrict activities to one editor at a time? An
activity is like a branch label. It is not uncommon for many developers to be
working on different resources in the same activity.

3.8.1 I don't understand this definition. I though the roots were the
collections that WERE added to the configuration. What's not included is their
members (recursively) although those members are included in the configuration.

3.9.1 Why is baselines plural? A revision of a versioned collection can only
have one baseline. A collection versioned resource can have many baselines, at
most one for each revision.

3.10.2 DAV:revisions is not consistent. The first sentence says it s a
collection of revision ids. The last sentence says it contains URLs of the
revisions. Should be revision ids like all other references to revisions in
properties (e.g., DAV:successors). How are the reserved characters escaped?

3.10.3 DAV:revision-labels is also inconsistent. It perhaps incorrectly uses the
term binding, implies labels are resources. Why is this included? It sounds like
an implementation detail. With the History Resource DAV:revisions property, and
the Revision DAV:revision-labels property, this can be calculated. In any case,
the binding name can't be that label as it must be scopped by the History
Resource since the same label can be applied to a revision of other History
Resources.

Section 3: we need to define DAV:resourcetype for all these new resources.

4.1.1 Perhaps we should define GET on the versioning resource to return empty
entities. Then we can change them later if needed.

4.1.2 meaning revisions of versioned collections cannot contain bindings to
unversioned resources? Why is this required? How would a new resource be added
to a working collection resource? 4.1.3 implies that a working collection
resource can contain a null resource which can't be a versioned resource.

4.1.3 Why is PUT on a null resource a special case creating a new versioned
resource. PUT on a nonexistent resource would create a resource and set its
contents. A subsequent checkin (if any) would make the resource a versioned
resource. PUT on a null resource should just set the contents of the resource,
and make it a non-null resource.

4.1.4 Again, we should think about DAV:link semantics and make property
resources consistent.

4.1.7 COPY of a revision creates a new resource, not a new versioned resource.
Should be able to copy a workspace.

4.1.9 There was a section in the model document that described locking on
workspaces, activities, and versioned resources. That section didn't get copied
into the versioning protocol introduction, and is not consistent with section
4.1.9. We need to revisit locking semantics.
- lock on revision prevents unauthorized checkouts of that revision
- lock on an activity prevents unauthorized modifications of the activity and
therefore checkouts in that activity
- lock on a workspace prevents unauthorized modification of the workspace and
therefore checkouts in that workspace
- lock on a versioned resource (History Resource in this version of the
document) prevents any unauthorized checkouts of any revision

4.1.0 We talked about a lot of other information in OPTIONS at Concord. Here's
my meeting notes: How is server versioning meta-data discovered? Properties on a
distinguished collection? On '/'? With OPTIONS? Consider two approaches:
implicit property on all resources, or OPTIONS on a resource or *. Properties
can be structured, options can't. Could consider extending options to take and
return an XML request/response body. Use PROPFIND semantics to specify the body.
Options exists because properties didn't. OPTIONS * is the only way to talk to
the server. Everything else is to a resource. Resolution: use OPTIONS with
PROPFIND entity request body on * for server and resources for meta-data on
resources. Returns server/versioning meta-data. Don't want this information on
allprop. Provides extensibility for OPTIONS. Geoff wants to use a repository
object so it can be a resource to provide extensibility. Want to put in the
repository: workspaces, activities, history resources, configurations, ...?
Discover the location of the repositories from OPTIONS *.

(MKRESOURCE and REPORT were reviewed from the updates Jeff sent out, not from
version 2.2 of the versioning spec)

MKRESOURCE should be able to initialize the contents as well as the properties
in a single operation. This ensures the resource is created in a consistent
state. We can't do this with the current protocol without using multi-part MIME
content for the request entity body for the properties and resource content. We
don't need this for versioning, but it seems like it would be useful for
completeness.

Results Marshalling: idempotent is not defined in Webster's dictionary. There
may be a lot of people (myself included) who do not understand the implications
of idempotnet semantics. Perhaps some explanation would help.

The status in the example is not included in the results marshalling. Should
have a successful example first.

REPORT:

DAV:conflicts doesn't sound right. A workspace RSR might specify lots of entries
that would generate conflicts that aren't interesting. The DAV:rsr-merge element
is to specify which elements in the RSR contribute to potential conflicts. Also,
DAV:conflicts isn't for a specified resource, its for the workspace. We could
include a target that was empty (all conflicts), an activity (conflicts with
this activity), a revision (is there a conflict with this revisions), or any
revision selector. But this is accomplished with the DAV:rsr-merge element in
the workspace RSR.

Results marshalling introduction was copied from MKRESOURCE.

Example 1, the D:reports-response should contain <D:conflicts/><D:conflicts/>,
etc. These should not be in PCDATA. See also section 1.2.3.2,
DAV:reports-request.

Example 2, the contributor should be a revision id just like
DAV:merge-predecessors, etc.

Example 3, D:added and D:deleted should take D:href elements too. This way the
report can included all the added (deleted) resources in one D:added (D:deleted)
element.

Last sentence after the examples was cut off. All of the format sections we cut
of when printed.

DAV:compare-response: {comment}, configurations don't have activities in them
directly, but the revisions in a configuration were created in some activity.

<!ELEMENT added (href+)>
<!ELEMENT deleted (href+)>
<!ELEMENT changed (href+)>

DAV:changed: (and added and deleted) need to explain the result separately for
workspace, configuration, activity, or versioned collection. The descriptions
given don't seem to adequately distinguish or fully describe them.

4.3.1 CHECKOUT, how do we distinguish between a checkout with an automatic
creation of a workspace, and checkout in the default workspace (which is used by
non-versioning aware clients)?

An activity need not be associated with a working resource, even if the server
supports activities. If an activity is required, then we should specify a
default activity instead of generating one for every checkout.

4.4.1 We need both a workspace header and revision-selection header. The
workspace header specifies what revisions of intermediate collections are used
to access the target resource while the revision-selection header overrides the
workspace RSR to access a particular revision. The revision-selection header
should specify a label, revision id, or any other revision selector suitably
distinguished.

5.1.5 latest should generate conflicts if connected with rsr-merge with other
revision selectors.

5.1 rsr-configuration and activity-latest carry redundant information. The
referenced resourcetype determines how the resource should be interpreted.
Specifying it in the RSR introduces a redundancy and the need to generate an
error at some point. When? When the RSR property is updated? When the workspace
is used? Ignore the rsr element and use the resroucetype? The problem is that
revision selectors are one of three types: workspace which selects either a
revision or working resource (which isn't quite a revision yet, or is it?),
activity or configuration resource which selects the member, and label or
revision id (which aren't resources). Somehow these should be normalized. Either
make a label a resource (might be too heavy), or just distinguish labels and
references (with an href).

Distinguish between using a URL to access a versioned resource vs. a revision
with a header similarly to the old direct references passthrough header. Suggest
boolean Versioned-Resource header which defaults to "F". If "T", apply the
method to the versioned resource instead of the revision (primarily for
PROPFIND/PROPPATCH).



Quick comparison to the model:

DELETE with Versioned-Resource header "T" deletes the whole versioned resource
and all its revisions.

Versioned resource properties include a list of mutable properties (so they can
be discovered), versioning options (DAV:checkin-policy policies that apply by
default to all revisions. Is automatically versioned property that applies by
default to all revisions. Can be overridden for any particular revision.

Didn't see any method for creating a baseline. Just a CHECKIN with depth:
infinity?

Model has a method to add or remove a label to the latest revision of all
resources in a given activity. This a client convenience, but something the
server can do a lot easier than the client. Include it if we think it is a
common operation.

Protocol doesn't specify how members are added to a configuration. The model has
methods to add and remove a revision (using the same revision selection
mechanism as any other method). This establishes the roots of the configuration.
Doing this as a PROPPATCH may not be sufficient because some action has to take
place when the element is added to add it members, check for existence of the
selection, etc.

The model has a snapshot method for the workspace that creates a configuration
containing all the revisions visible in the current workspace. This effectively
creates a configuration that can replace the RSR for the workspace in order to
select the same revisions at some time in the future. This is a very common
requirement.

Model has a method to add a label to a collection with depth.

Model doesn't have an explicit resource factory that can be used to implement
MKRESOURCE. It is implicit in constructors, but they don't take properties as an
argument.