Next message: Geoffrey M. Clemm: "Re: Revision of a stable-URL versioned resource"
Date: Sat, 8 Apr 2000 00:51:57 -0400 (EDT)
Message-Id: <200004080451.AAA05848@tantalum.atria.com>
From: "Geoffrey M. Clemm" <geoffrey.clemm@rational.com>
To: ietf-dav-versioning@w3.org
Subject: Re: versioning-04 review
Another great review, Jim!
From: jamsden@us.ibm.com
- Is the history report covered by the properties report?
Yes.
If so, the spec should show it as an example.
Done (good suggestion!).
- There seems to be some confusion with respect to default revision
selection. The spec says in various places that the default revision is a
property of a versioned resource,
Removed.
a versioned collection for picking
default revisions of members of that collect,
Removed.
and by using a server default workspace.
How about just replacing this with the SET-DEFAULT-REVISION method
that Chris suggested back in the dawn of time (a loud "I told you
so" from Chris is probably warranted at this time :-).
Having a versioned resource have a default revision is good for
basic versioning, but it isn't scalable as a client would have to set the
default revision individually for every resource on the server.
An advanced versioning server can provide the ability to
merge baselines or activities into the workspace to
change the revision selection for lots of versioned resources in a
consistent way.
It also
introduces two mechanisms for specifying default revisions, one for basic,
and the default workspace for advanced. This needs some thought. See a
suggested solution below in comments on section 2.4.
Yes, I agree that is to be avoided.
- Also some confusion on the use of workspaces as a "checkout token" in
basic versioning. Tim's scenarios indicate the client has to create a
workspace to be used as a checkout token (or working resource identifier).
Then this workspace is used to identify all checked out working resources.
The spec says the server returns a workspace for each checkout that
identifies the associated working resource, one per checkout. I think a
compromise is appropriate. If a workspace is not specified on a checkout,
then the server creates one and returns it along with the working resource.
If the client does specify a workspace on the checkout, the server uses
that one to identify the working resource. If that workspace already has a
working resource for the same versioned resource, then an error is returned
(since the same workspace cannot identify more than one working resource
with the same versioned resource URL).
Yes, this compromise is what I tried to present in the protocol document.
If this is not clear, we need to fix up the language to make it clear.
The only modification I'd make to your description is that when a workspace
is not specified on a checkout, the server "allocates" a workspace ... it
does not necessarily have to create a new workspace. This allows an advanced
versioning server to "reuse" workspaces to handle core versioning CHECKOUT
requests.
Then clients can choose what they
want to do. A client could create workspaces as identifiers for related
work, and use them to check out revisions. Or it could let the server
create the workspace, and then just hand it back on accesses in order to
identify the working resource. Comments below are based on this working
assumption.
Yes. But note that a core versioning server is only required to
support the "server allocates the checkout workspace" mechanism.
Chris has requested this, and I believe we agreed to it. An
advanced versioning server may optionally support a user creating a
workspace resource and specifying that with the CHECKOUT request.
- 1.2 Workspace: A "workspace" is a string used to identify a particular
working resource of a versioned resource. It MAY be generated by the server
or created by a client.
The "may be created by a client" appears in the advanced versioning section.
- 1.2 Target: Workspace and Version-Selector should be Revision-Selector.
Fixed.
- 2.1 end of 2nd paragraph: add: See below for details describing how
workspaces are used to identify working resources. (needs a forward
reference).
Isn't the terminology section's definition of a workspace as "a string that
identifies a working resource" sufficient?
- 2.2 1st paragraph 2nd sentence: A working resource of a versioned
resource is given a server assigned workspace when it is created if the
client does not specify a working resource on checkout. Alternatively the
client may choose to create a workspace and use it on subsequent checkouts.
This functionality is introduced in advanced versioning.
- 2.4 last sentence: need to determine how default revisions are selected.
If it is done simply by issuing a SET-DEFAULT-REVISION method,
it probably doesn't need much description in the text.
This section describes default revisions as a property of a versioned
resource. Section 8.1 and 9.1 describe default revision selection using the
default workspace. Section 8.1 associates the default workspace with a
collection. 4th paragraph in section 9.1 describes the default workspace
associated with the server. Let's discuss this one. Perhaps the best
solution is to provide an optional default revision associated with a
versioned resource, and an optional default workspace associated with the
server. If neither are specified, no revision is selected. If both are
specified, the default revision associated with the versioned resource
takes precedence.
Yes, I agree this all needed to be cleaned up. Is the approach of
"core versioning uses a SET-DEFAULT-REVISION and advanced versioning
allows the use of MERGE for activities and baselines" acceptable
(it certainly is much simpler and more consistent).
- 3.1.2 then when appropriate escaped -> then appropriately escaped...
Fixed.
- 3.3 Use DAV:versioned-resource instead of
DAV:versioned-resource-resourcetype. Its too long, not consistent with
DAV:collection, and redundant with
<DAV:resourcetype>DAV:versioned-resource-resourcetype</DAV:resourcetype>.
Similar comments for all other resource type identifiers.
Done.
- 3.3.1 Use DAV:revisions instead of DAV:revision-set. This is better
English and is consistent with our common use of the terms. It doesn't
matter that its a set, only that there are many members.
I'll let you and Jim Whitehead hash this out ... he didn't like
DAV:revision and DAV:revisions because they'd be easy to confuse.
- 3.3.3 This is pretty ugly. First its a mouthful of special cases. Second,
it allows a down-level client, unaware of versioning, to change the default
revision on a resource other clients might be using without even knowing
about it. I prefer using the default workspace for this, and allowing
servers to have DAV:latest as the only entry in the revision selection rule
(effectively). Gets the same result, but cleaner. This doesn't mean servers
have to support extended workspaces. They can special case the default
workspace implementation.
I believe the "set-default-revision" for core and "merge" for advanced
is as simple, and allows us to defer the concept of a workspace as a
resource to advanced versioning.
- 3.3.4 Indicate checkout, operation, checkin must be atomic.
Done.
- 3.4.2 DAV:revision brings up a common problem with stable URLs. The
client is generally using versioned resource URLs and revision selectors
like revision labels, workspaces, activities, etc. But many methods return
stable URLs representing functors the server uses to access specific
revisions.
Now that workspaces are stable (i.e. do not do dynamic revision
selection), there is no need to return stable URL's as a result of
methods. I am in general firmly against returning information the
user did not ask for, just in case it might need it.
Given one of these stable URLs, how can the client determine the
versioned resource and labels that should be reported to the user in order
to provide more meaningful names?
It shouldn't. The user knew which resource it was applying the request
to (it specified its URL). If it wants to know additional information about
the resource, it can ask for it.
I suppose the client can follow the
stable href to the versioned resource to get its URL and to the revision to
get its revision id or labels, but this is a lot of requests to get
information the client will almost always need. Perhaps we should consider
returning a versioned resource/revision id pair to reduce the problem.
The DAV:property-report allows a client to obtain this information
in one REPORT request.
- 3.4.5 2nd paragraph: What is this trying to say? That revision labels are
URL segments and can be URL encoded for transmission?
I'll just get rid of this sentence.
- 4.2 needs specific status codes assigned. Just pick the next available
numbers.
I assume we get them from IANA or ... ?
- 5.1 Postconditions is worded kind of funny. "If the response status code
is 201..." On successful execution, the resource is created with an empty
body and its properties initialized as given in the request entity body.
Last paragraph: If execution fails, no new resource is created and any
resource that may have existed at the request-URL is unaffected.
Why is a reference to the status code funny? That is more concrete than
"if the execution fails".
- 5.2.2 Remove status from the element definition. (reports, conflict, or
compare) should be (property, conflict,... There's no reports report. There
is an available reports report though.
Done. I cleaned all this up alot, since a lot of the report elements
were just noise.
- 5.3.3 <D:available-report-request/> in the <D:report-request>
Done.
- 5.4 Needs motivation. What would anyone do with a property report? Is it
used to get the revision history of a revision or versioned resource? If
so, how?
Fixed (added the example you suggested).
- 6.1, 3rd postcondition: what is DAV:resourceid? (I don't have the binding
spec with me).
It's now called DAV:urn. I think this is actually wrong ... i.e. it's
not that the revision gets the same DAV:urn, but rather that PROPFIND
returns the DAV:urn of the versioned resource, not the DAV:urn of the
revision. I'll write this up and see if it is clearer that way.
- 6.1, last postcondition, what does it mean to have a versionable resource
replaced in its parent collection by the new versioned resource? Is this
just a new binding? If so, this is what it should say.
Fixed this to just say "converts it to a versioned resource".
- 6.1 Need a status code for already versioned?
Ah yes, the perennial question of whether to create a more specific
error code or re-use an existing generic one. I could go either way.
- 6.2 The client should be able to specify a workspace too.
In advanced versioning.
- 6.2 2nd request marshalling: is a little confusing. The precondition
indicates the request-URL has to be a stable href to a revision, or a
versioned resource with either a workspace header, revision-selector
header, neither (in which case the default revision is selected), or both.
What part of that is confusing?
- 6.3 2nd request marshalling: The workspace header specifies the workspace
that identifies the working resource.
Fixed.
- 6.4 Last sentence in the intro: "If the server supports mutable revisions
and there is a single predecessor revision, then CHECKIN can be used to
overwrite the value of the predecessor revision." Here is an excellent
example of why we need to distinguish between predecessors created with a
checkout, and merge predecessors.
Why is that? I suppose you could say "has no merge predecessors" instead
of "has only one predecessor", but I don't see the significant difference.
Another is that the MERGE method should
not be allowed to remove a predecessor created from a checkout, only
predecessors created by a merge. Otherwise the line-of-descent and revision
history wouldn't be meaningful.
I think the whole business of removing a merge arc is probably bogus
(I think I suggested allowing it, so we know who to blame :-).
The likelihood of you wanting to do that is so small that I think it
is easier to just do an uncheckout in that case, and start the merge
over again. Anyone object?
- 6.4 Response marshalling: 207 multi status might be returned too in order
to indicate which checkin policies couldn't be satisfied. And I thought
these policies were applied on checkout too so that a client wouldn't be
able to checkout a revision with an expectation of how it could be checked
in if that expectation could not be met.
Yes, our favorite "how to report the error" question (:-).
I'm inclined just to bundle all the checkin-policy failures
as a 405, but I can go either way on this.
- 7.1 If the Workspace-URL is omitted from the Workspace header, the
versioned resource itself is the target of the request. This is confusing
and irregular. Consider using the Revision-Selector as described below.
Yes, based on the stable URL discussion, it looks like we've agreed to
just get rid of this whole concept of a "metadata" workspace header.
- 7.2 add | "Revision-Selector" ":" "Versioned-Resource" to indicate the
versioned resource is selected. Target-Selector is better in this case.
I don't follow this. Why would you put a versioned resource in the
revision selector header?
Note the extra space in the " Revision-Selector: for label. Should be
removed.
Done.
- 8.1 For the new workspace semantics, distinguish static and dynamic
workspaces, and that dynamic workspaces are optional. Dynamic workspaces
keep the revisions in the workspace consistent with the workspace revision
selection rule at all times and under all circumstances. Static workspaces
require the client to refresh the workspace to see revision selection
changes.
If we have no revision selection rule, but only a baseline list
(which is guaranteed to be immutable), we can avoid the whole topic.
We've discussed this somewhat, but I'm sure we'll discuss it some more (:-).
- 8.1 A default workspace should not be associated with a collection, it
should be associated with the server. That's probably complicated enough.
Agreed. Replaced this with the statement that the server allocates default
workspaces, possibly different ones for different URL's.
- 8.1 Conflict Report: perhaps we should eliminate DAV:merge operators in
the revision selection rule, and have the conflict report be the entity
response body from a MERGE request.
We probably still want a way to let the client find out what conflicts
a MERGE would encounter, rather than requiring they actually request one
to find out. I've changed this around, so it is just "what conflicts would
I get if I did the following MERGE to the specified workspace".
It should be possible to merge two
resource to set the successor/predecessor relationship, and to merge two
workspaces to include changes made in one workspace into another workspace.
We certainly need to allow a baseline created from one workspace
to be merged into another workspace. Do we also need to allow merging
the contents of a workspace into another workspace? If so, we need
to define what happens when the source workspace selects a working
resource? You can't merge one working resource into another, so we'd
have to either say "you can't merge from a workspace that selects working
resources", or say "if the workspace selects a working resource, the
DAV:predecessor revision of that working resource is merged".
I'm not too happy with either of those, and so am tempted to just
say "to merge from a workspace, you first have to create a baseline
in that workspace, and then merge that baseline". This has the
further advantage that it leaves the destination workspace in a much
more predictable state.
Or merge an activity into a workspace to pickup the changes made in that
activity.
Done.
For example, merge a user's working area workspace into the team
integration workspace. The conflict report would be generated by the merge
request. Just keep merging until there are no more conflicts.
I suggest we have the merge operation do all the checkouts needed to
represent the merge. The user can then go and do all the merges
indicated by those checkouts.
Maybe the target of the merge should always be a workspace, and the source
a revision, activity, configuration, or workspace.
Agreed. I'm still on the fence about merging a workspace into another
workspace, for the reasons stated above.
- Remove baseline, its redundant with a configuration containing a single
collection.
I think we currently have settled on removing "configuration", since it is
redundant with "workspace". Then a baseline is just a revision of a
versioned workspace.
There's no reason to have a special place for these
configurations (baseline property of a versioned collection). Users should
be free to put them where it makes the most sense for them.
We're dealing with this topic in another thread (:-).
- Remove repository. There are no methods that do anything with it but
setting properties. The properties are never used. More comments in the
appropriate sections below.
Done (but there is the DAV:repository-report to take its place :-).
- 9.1 consider having only DAV:rsr-or (or no operator since that would
leave only one) operator in the revision selection rule. Generate the merge
conflict report as the result of a merge operation.
DAV:revision-selection-rule is now supplanted by DAV:predecessors,
indicating the predecessor baselines for the workspace.
- 9.4 Remove the second paragraph referencing deep revisions and baselines.
Done.
- Remove 10.2.1 and 10.2.2, DAV:baselines and DAV:repository.
Done.
- 10.5.1 Perhaps there should be a way to list all the members of a
workspace, not just the working resources.
That's a pretty big report! Also, they will just be revisions
shared with many other workspaces, unlike the working resources that
are owned by the workspace.
- 10.5.2 consider removing DAV:rsr-merge and get the conflicts from the
merge method. ...
- 10.5.2 Here's another case where the stable URLs in the revision
selection rule won't be very meaningful to a client. How could the client
efficiently get back more meaningful versioned resource URLs and labels?
- 10.5.2, Consider removing the last paragraph: DAV:rsr-merge.
Got rid of all the rsr's.
- Remove 10.5.4 DAV:current-label and 10.5.5 DAV:current-activity. They
should no be necessary to keep the checked in revision visible in the
workspace. Specify the activity in an Activity header on CHECKIN.
DAV:current-activity is still needed to give versioning-unaware
clients access to advanced versioning servers that require an
activity for checkout. This way a versioning client can set up
a workspace for use by a versioning unaware client.
- 10.7 DAV:configuration not DAV:configuration-resourcetype.
Done.
- Remove 10.7.1 DAV:baseline-root.
Done.
- Remove 10.8.1 DAV:versioned-resource-collection. This looks like an
implementation detail that clients never need to know. Its never referenced
in any method.
- Remove 10.8.2 DAV:repository-root, another implementation detail clients
never need to know. Its also never referenced in any method.
- Remove 10.8.3 DAV:activity-collection. This is contrary to namespace
management. A client should be free to create any resource in any namespace
he creates in order to organize them in the way that makes the most sense
for their project and/or development process. Servers may have
restrictions, and may refuse to create collections or bind members of
certain types in other collections. But this is nothing new. This property
is also never used in any method.
- Same for 10.8.4 DAV:configuration-collection.
Got rid of all of 10.8 (but introduced the DAV:repository-report,
indicating if the server restricts placement of versioning metadata).
- 11 Why can't a versioned collection contain a member denoting a binding
to an unversioned resource? Its the collection that doesn't change, not the
resource the collection member refers to.
This would mean that a workspace containing such a collection revision
cannot make a copy of that collection for use by the workspace, but
instead needs to have every workspace with that revision share a common
(mutable) unversioned resource. This removes the essential characteristic
that allows one to implement large numbers of workspaces working against
a common set of versioned resources.
Does this result from collection baselines? If baselines are
removed, does the restriction go away?
No, and no.
Need motivation in any case.
Addes a bit, but may need more.
- 11.1 this should refer to dynamic revision selection by the workspace if
supported by the server. It has no effect for static revision selection.
Without dynamic revision selection, we don't need to say any of this
(thank goodness!). The whole idea of "version locking" segments of the
namespace is just too complex to contemplate.
- 11.2 1st two paragraphs should apply to basic versioning too in order to
support "checkout token" reuse.
Chris didn't want to require checkout token reuse for core versioning.
If you can change his mind, I'd be happy to move it to core.
Last paragraph should be removed.
Activities should be specified as part of checkin. So this section isn't
needed, advanced versioning doesn't add anything.
Needed to allow versioning aware clients to set up activity-based
workspaces for use by versioning unaware clients.
- 11.3 Can remove this section. Advanced versioning doesn't add anything
here either.
Still need to mention the activity stuff.
- 12.1 Conflict report should be the output of a MERGE operation, not a
derived property of a workspace. That way conflicts can be determined for
either static or dynamic workspaces and the DAV:rsr-merge operator in the
revision selection rule isn't needed.
I agree that a conflict report should just "what a merge would do",
but I still think we need the report, since a user might want to find
out what the merge would do before requesting it.
- 12.2.3 The href's in the D:added elements could be combined into one
D:added element (<!ELEMENT (href+, ANY*)>) to simplify the report results.
I was thinking that a server is likely to add additional stuff to the
add report to describe what was added, and I wanted to make sure that
it was unambiguous to the client what added element this additional
info applied to.
- 13.1 Shouldn't be able to delete a predecessor that was created with
checkin. Shouldn't be able to delete all predecessors and leave the
revision dangling.
Agreed. Got rid of the delete predecessor functionality.
- Need a way to merge workspaces, activities, and configurations and
generate a conflict report. The use case is for a user to have a working
area workspace, and for there to be a team integration workspace. The user
wants to catch up with changes made in the team integration workspace by
merging the team workspace into their working are workspace. Conversely,
the user wants to release his changes into the team workspace by merging
them into the team workspace. Similar for activity and configuration.
Done.
So there are two merge operations. On that detects attempts to refresh a
workspace and detect conflicts, and another that resolves conflicts for
individual revisions.
Can do this with one merge operator, I believe.
- 13.2 Here's another case where stable URLs will need to be translated by
clients into at least versioned resource URLs and revision ids.
Got rid of the CONFIGURE operation, since don't have configurations
anymore. Achieve similar effect by merging into a workspace, without
needing to deal with stable URL's.
Should also have a way to create a configuration from workspace in a single
method.
Now that they are the same thing, there is no need to convert back and forth.
- Need to specify the members of a workspace, not just the revision
selection rule. That is, the revision selection rule may select revisions
of resources the client is not interested in. The workspace needs a scope
defined by its members where the revision selection rule specifies what
revision of the members will be (or was on the last refresh) selected.
Without a revision selection rule, this is no longer ambiguous.
- 13.3 Remove this section, just use a configuration with one member and a
depth header on add.
Got rid of this constrained notion of baseline.
If not removed, first precondition is confusing. The DAV:baselines
property, being plural, implies there may be many baselines for a versioned
collection representing different configurations of that versioned
collection. But the precondition indicates the DAV:baselines property must
not exist and that the BASELINE method creates it with a single baseline.
How are multiple baselines supported? Does the client have to remove the
DAV:baselines property before creating a new baseline?
Should indicate a baseline is a configuration with one collection member
and depth infinity. This is implied in the postconditions, but is not
stated in section 9.4.
Yes, this is all confusing. Just replaced it all with the "baseline is
a revisin of a versioned workspace" concept.
- 14.1 as described is correct for dynamic workspaces. Static workspaces
select the member that was added to the workspace on the last refresh. Note
also that a workspace should have a scope specifying what versioned
resources are included in the workspace as well as the revision selection
rule.
Fixed by removing dyanmic revision selection.
- 25 Open Issues:
authority and host header in examples seems to be done.
Yes.
activity as CHECKIN parameter should be the only way activities are
associated with a revision.
See above.
don't allow CHECKOUT to apply to a versionable resource. Require VERSION
first.
Done.
don't use MKRESOURCE to create a baseline. If baselines are retained, use
the BASELINE method as described.
Now created by applying CHECKIN to a workspace.
remove references to repository.
Done.
The WebDAV working group decided MKRESOURCE was preferable over PROPPATCH
on a null resource at the December IETF meeting.
Yes.
A configuration can't contain working resources, so a configuration
containing a collection revision depth infinity could not attempt to
include any working resources.
Done.
There is no need for a options call to enumerate the repositories and
workspaces. Repositories are unnecessary, and clients are expected to know
the meaning of namespaces they create.
In our last conference call on the topic, the group voted the other
way, so I'll remove this note, but with the opposite resolution (:-).
Thanks again for all the hard work reviewing the protocol, Jim!
I'll try to get a 4.1 draft up on the server with these changes
and with changes discussed on the mailing list.
Cheers,
Geoff