Re: WeDAV Versioning Summary
jamsden@us.ibm.com
Thu, 15 Apr 1999 17:14:32 -0400
From: jamsden@us.ibm.com
To: ietf-dav-versioning@w3.org
Message-ID: <85256756.0000DF62.00@d54mta03.raleigh.ibm.com>
Date: Thu, 15 Apr 1999 17:14:32 -0400
Subject: Re: WeDAV Versioning Summary
See <jra> below. Geoff, you didn't have any issues with the section on
locking?
"Geoffrey M. Clemm" <gclemm@tantalum.atria.com> on 04/14/99 06:33:57 PM
To: Jim Amsden/Raleigh/IBM
cc: ietf-dav-versioning@w3.org
Subject: Re: WeDAV Versioning Summary
Some minor wording nits ...
I'd like to thank Jim again for a truly *excellent* write-up!!
<jra>
Thanks. And you're more than welcome.
</jra>
Cheers,
Geoff
From: jamsden@us.ibm.com
Introduction
This document summarizes the semantics and rules for WebDAV versioning
that
have been discussed the last few weeks on xml-dav-versioning. This
document
doesn't present a lot of alternatives, motivation for why we picked one
semantic over another, or raise any issues. These will come later. I
will
however try to present versioning, parallel development, configuration
management, and Document Management Systems semantics as simply and
completely as possible so we can see the big picture. Assuming we can
nail
down these semantics, the protocol should be pretty straight forward to
design.
WebDAV Versioning Summary
The following is a brief summary of the WebDAV semantics for supporting
versioning, parallel development, and configuration management. This
summary does not describe the details of the protocol, only the high
level
semantics the protocol is intended to support.
Creating Versioned Resources
A resource or collection can be put under version control. Putting a
resource under version control creates a versioned resource and sets its
initial revision to the resource.
Perhaps "creates an initial revision that is a copy of that resource".
<jra>
I changed it to "creates a versioned resource and converts the resource
into the initial revision". I didn't want to use copy because that would
imply a WebDAV copy which would mean the original resource somehow still
exists.
</jra>
A checked in revision cannot be modified
by anyone at any time.
When a resource is put under version control, the server generates a URI
for each revision that may be used to explicitly access that revision.
These URIs are globally unique and are never reused for any other
revision.
Naming Revisions: revision ids and labels
A revision of a versioned resource is given a system assigned revision
id
when it is checked in. This revision id acts as an immutable identifier
distinguishing this revision from all others of the same versioned
resource. A revision id can be assigned to only one revision of a
versioned
resource, and can never be reused on that versioned resource.
A user may assign other revision names called revision labels to a
revision
in order to distinguish it from other revisions using more meaningful
names. These revision labels must be unique for any given versioned
resource, but may be reassigned to any revision of the versioned
resource
at any time. Revisions of different versioned resources may have the
same
label.
There is a distinguished, floating label called "latest" which
always refers to the latest revision in a given activity.
The default semantics of adding an activity to an RSR is "latest in
the activity", so there is no need for a "latest" label. In addition,
when there are multiple parallel activities adding revisions to a
versioned resource, it would be ambiguous which one "latest" referred to.
<jra>
By "latest" I mean latest in time regardles of activity. I agree this has
limited usefulness. Using some "mainline" activity (like DSEE) would
probably be better. I had included it for servers that don't implement
activities. Is this OK?
</jra>
So I suggest we just strike that sentence.
Modifying a Versioned Resource
A versioned resource may be modified by checking out a revision to
create a
working resource. A working resource can be updated (PUT, PROPPATCH,
etc.)
any number of times. When updates are complete, the working resource is
checked back in. Users can use checkout/checkin to register intent to
modify a versioned resource similar to the way lock and unlock are used
in
DAV level 2. The sense is reversed though. A checked in revision cannot
be
changed without checking it out first.
A revision may be checked in as mutable or immutable. If the revision is
mutable, a subsequent checkin of a working resource may be done in place
allowing the mutable revision to be updated in place without creating a
new
revision. A working resource created by a checkout of a mutable revision
can also be checked back in creating a new revision if the user wants to
retain the previous revision. If the revision is immutable, any checkin
of
a working resource derived from this revision must create a new
revision.
The mutability of a revision cannot be changed once it has been
established
on an initial checkin.
Servers may choose to not allow revisions to be checked in as mutable,
or
they may not allow a revision to be checked in without creating a new
revision. These constraints are typical of current configuration
management
systems. Document management systems typically allow revisions to be
mutable and don't have these restrictions.
A revision of a collection is modified by adding or removing member
URLs.
Using the new "bind" semantics, "by adding and removing bindings to
other versioned resources".
<jra>
Should be bindings to other revisions not versioned resources? I'd like to
leave this description pretty generic where the "members" of the
configuration are somehow revisions identified by some means. Then we can
cover the details in the model and protocol after bind/reference issues are
resolved. OK?
</jra>
Changing the contents of a member of a revision of a versioned
collection
does not imply a change to that revision of the versioned collection.
"In particular, adding a new revision to a versioned resource does not
require a new revision of a versioned collection that contains that
versioned resource". You say this below, but it might be worth setting
up this idea up front.
<jra>
I included a forward reference.
</jra>
Development with Activities
Resources are checked out in the context of an activity. An activity
abstracts a set of related changes a user is making to versioned
resources.
Each activity represents a thread of development. Servers may support
multiple sequential activities that can be used to enable controlled
parallel development. These different activities can be merged together
at
some later time in order to integrate the changes.
Servers that don't
support parallel development effectively only support one, default
activity.
I'd strike the preceding sentence.
<jra>
Its gone.
</jra>
A revision that is already checked out in an activity cannot be
checked out again in the same activity. If parallel development is
desired,
a user can checkout the revision in another activity and merge them
later.
Simple parallel development can be accomplished by using the null
activity.
A server may allow many checkouts of the same revision using the null
activity. Merge is not supported for the null activity, client
applications
are responsible for integrating the changes.
I'd replace the preceding paragraph with the "current label" description
posted earlier.
<jra>
Done.
</jra>
Selecting Revision through the Workspace
Resources, working resources, and revisions of versioned resources are
all
accessed using a URL. Specific revisions of a versioned resource can be
accessed by specifying the server generated revision URI, or the
resource
URL and a version label. However, versioned resources are usually
accessed
using a simple, human meaningful URL. The revision selected when a
specific
revision name is not specified is resolved through a workspace. A
workspace
provides a mapping between URLs for versioned resources, and specific
revisions. This allows versioned resources and unversioned resources to
be
accessed the same way. As a consequence, relative ULRs continue to work,
and DAV level-2 clients that are not versioning aware are able to
access
versioned resources.
A workspace contains a current activity and a revision selection rule.
Revisions are selected using the following rules in order: If the URL is
to
a unversioned resource, then that resource is selected. If the URL is to
a
checked out revision, then it is selected. Otherwise the workspace
revision
selection rule is applied to select the revision. If there is no
matching
revision, then a resource not found status is returned. This rule is
applied to collections to select the revision that determines their
member
URLs, and to other resource to determine the revision containing their
contents.
A workspace revision selection rule can specify any number of revision
labels, activities, configurations, or the functor "latest" to specify
what
revision to select. The rules are applied in order until the first match
is
found. Any subsequent potential matches are ignored. A label matches a
revision with that label. An activity matches the latest revision in
that
activity, and may result in merge conflicts. A configuration matches a
revision contained in that configuration. Latest matches the latest
revision.
Probably worth noting here that "latest" is just based on modification
time,
and is independent of the predecessor/successor relations created by
checkin/checkout.
<jra>
Done. See comments above about latest too. This looks like you agree with
those concepts.
</jra>
If a request is made and no workspace is specified, a default workspace
containing the null activity and "latest" in the version selection rule
is
used.
I'd say "a default activity", rather than "the null activity".
"Alternatively, the default workspace can contain the current-label
"default", and with label=default in the version selection rule".
<jra>
Actually, the workspace could contain both. They're not mutually exclusive.
The default activity isn't the same as the null activity. Instead I sould
have said no activity. I'm not sure there is a default activity anymore. Is
there?
</jra>
Administrators can change the current activity and revision selection
rule of this default workspace to have such down-level client requests
done
in some other activity, or to support access to more specific revisions
of
versioned resources.
A resource revision is checked out in the context of a workspace which
is
used, with the resource URL, to subsequently access the working
resource.
If a workspace is not specified on checkout, a new workspace is created
as
a "checkout token".
The server is allowed to use an existing workspace instead of creating a
new workspace, so this should probably be "the server allocates a workspace
for the checkout, possibly reusing an existing one, and returns this
workspace
as a `checkout token' for use by the client to identify the working
resource."
<jra>
I dont' think this is the case. Only users can reuse workspaces (tokens or
not) because reusing a workspace implies being able to see working
revisions checked out in that workspace. You wouldn't want a server
automatically making someone else's checkouts visible to you.
</jra>
This workspace has no current activity, and no revision
selection rule. It can only be used to access the checked out working
resource. Client applications that wish to do their own URL to revision
mappings and not rely on server workspaces may use these checkout tokens
and revision GUIDs to do so.
"... may use these workspaces as checkout tokens ..."
<jra>
Done
</jra>
Configuration Management
A workspace represents a volatile set of revisions. Any new checkouts,
changes to the current activity, merging operations, or changes to the
revision selection rule may result in the selection of different
revisions.
A configuration is a resource that represents an immutable set of
revisions. A configuration contains a specific revision of each member
versioned resource. A configuration cannot contain a mutable revision
because the semantics of configurations cannot be guaranteed.
I'd avoid the word "contain" here, since I still believe we do not want to
model configurations as collections, but rather as "opaque resources" that
can be placed in a workspace to recover a saved configuration. This allows
far greater flexibility in implementation by the server. But that is
a topic of current discussion (:-).
<jra>
The words member and contain are intended to be generic and have their
usual semantic meaning rather than implying a configuration is a kind of
collection or not. Whether we make this distinction depends on whether or
not we need to inherit collection semantics for configurations. One way to
do this is to have the configuration members simply be URLs that are
references to revisions of versioned resources. However, this is not the
only way a configuration could be implemented. So I'm not that stuck on if
its a collection or not. Its just nice to reuse concepts where possible as
it is a good indication the original concept was useful.
</jra>
A workspace
whose version selection rule contains a configuration will always return
the same revisions as long as there are no revisions checked out.
Yup.
Versioned Collections
A collection contains a set of member URLs. For versioned collections,
the
members refer to versioned resources, not particular revisions. To add
or
remove members from a revision of a versioned collection, it must be
checked out just like any other resource. Creating a new revision of a
member, or modifying a member has no effect on the collection. Deleting
a
versioned resource that is an internal member from a collection does not
delete the versioned resource, it only deletes the member from that
version
of the collection. The resource may still be a member of a previous or
subsequent revision of this or some other collection. The URL for a
collection without a particular revision name is resolved to a
particular
revision using the workspace the same as any other resource. If the
collection is part of a URL for some other resource, then its members
are
determined from the selected revision.
Revision History
Each revision has a predecessor relationship with the revision it was
checked out from, and a successor relationship with revisions that were
checked out from it. Revisions may also have merge predecessor/successor
relationships with other revisions. A merge predecessor is a merge
source
while the merge successor is the merge target and contains changes from
the
merge predecessor as well as the predecessor. The revision history of a
versioned resource is the directed acyclic graphic (DAG) made up of all
its
revisions from the initial revision to all tip revisions in all
activities
in which this versioned resource was modified. The revision history
contains sufficient information so that a client may display or sort the
history by last modified properties.
Merging
Each activity represents a separate parallel thread of development.
Users
make their changes in the context of an activity. Changes to the same
revision must be done in separate activities or by using the null
activity.
Strike the "null activity" reference.
<jra>
I changed it to no activity.
</jra>
At some point, a user may want to merge changes made to the same
revision
together to create a new revision containing the combined updates. This
is
accomplished by merging an activity into a workspace. In order to do a
merge, it is first necessary to determine what must be merged. A merge
conflict report lists the resources that have been modified in parallel
in
different activities. The merge conflict report is generated using the
following rules: 1) if the merge source specifies a predecessor of the
revision selected by the workspace, then the workspace revision is
selected, else 2) if the merge source specifies a successor of the
revision
selected by the workspace, then the merge source revision is selected,
else
3) the merge source and the current workspace specify revisions that are
on
different lines-of-descent, and a potential merge conflict exists and is
included in the merge conflict report.
A user can request the differences between two revisions of a resource
(servers may provide a differences report, but they must at least
indicate
if they are the same or not). A user can request conflicts between an
activity and the current workspace to generate a merge conflict report.
A
user can also request the differences between a configuration and the
current workspace which lists at least the activities that are contained
in
the configuration but not in the workspace and vice versa. So
differences
are detected at different levels: content differences for resources,
revision differences for activities, and activity differences for
configurations.
Once the merge conflicts are known, a user resolves the conflicts by
merging the source activity with the workspace. This enters the merge
source into the workspace, and sets the current conflicts that must be
resolved. The conflicts are resolved by merging the revisions from the
merge source into the revision selected by the workspace to create a new
working resource. Servers may perform some default auto merging, but at
a
minimum, the merge is done by checking out the revision in the current
activity and noting the merge from the merge source. This creates a
merge
successor/predecessor relationship between the merge source and
workspace
revisions called merged-from. The conflict is now removed because the
working resource is now a successor of both the source and target
revisions. It is the user's responsibility to apply the differences in
the
two revisions in an appropriate manner. The merge is complete when all
the
conflicts are resolved, all differences have been merged, and the
resources
are all checked back in. The merge source can now be removed from the
workspace as all of its changes are now included in the current
activity.
When merging mutable revisions, the merge conflict report may be
inaccurate
as the source revision may change without the system being aware. Users
are
responsible for applying any changes to ancestor revisions to their
descendants as appropriate. The system cannot determine if there are any
changes that need to be applied other than by looking a the
last-modified
dates of the revisions.
Locking Versioned Resources
Locking a versioned resource prevents any revision from being checked
out
in any activity. Locking a revision of a versioned resource prevents
just
that revision from being checked out in any activity. Locking an
activity
prevents any revisions from being checked out in that activity. Locking
a
workspace prevents any checkouts in the current activity of that
workspace
(similar to locking the current activity), and prevents changes to the
workspace revision selection rule.