WeDAV Versioning Summary
jamsden@us.ibm.com
Thu, 20 May 1999 19:03:21 -0400
From: jamsden@us.ibm.com
To: ietf-dav-versioning@w3.org
Message-ID: <85256777.007EF3C8.00@d54mta03.raleigh.ibm.com>
Date: Thu, 20 May 1999 19:03:21 -0400
Subject: WeDAV Versioning Summary
Here's a update to the versioning summary. In particular, the section on
configurations has changed significantly to reflect our current understanding.
Thanks to Geoff for the thorough review.
---------------------- Forwarded by Jim Amsden/Raleigh/IBM on 05/20/99 07:01 PM
---------------------------
|------------------>
| Discussion |
| Main Topic |
| |
| Jim |
|Amsden/Raleigh/IBM|
| 05/07 08:37 AM |
| |
| |
|------------------>
>------------------------------------------------------------------|
| . |
| |
| Subject: |
| . |
| WeDAV Versioning Summary |
| . |
| Category: |
| |
| |
| |
| |
>------------------------------------------------------------------|
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. It does try to present
versioning, parallel development, configuration management 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.
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 converts the resource
into the initial revision. 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 the
versioned resource as a whole, and for each revision that may be used to
explicitly access that revision. These URIs are globally unique and are never
reused for any other versioned resource or 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
revision selector called "latest" which always refers to the latest revision
based on last modified time.
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 class 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.
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.
Selecting Revision through a Workspace
Resources, working resources, versioned resources, and revisions of versioned
resources are all accessed using URLs. Specific revisions of a versioned
resource can be accessed by specifying the server generated revision URL.
However, revisions are usually accessed using a simple, human meaningful URL for
a versioned resource. The revision selected from a versioned resource can be
specified by a specific revision name. A workspace may also be used to provide
a mapping between a versioned resource and specific revision of that versioned
resource. The mapping is specified by setting the revision selection rule of a
workspace. This allows versioned resources and unversioned resources to be
accessed the same way. As a consequence, relative ULRs continue to work, and DAV
class 1 or 2 clients that are not versioning aware are able to access versioned
resources through a default workspace.
A workspace may contain a current activity and a revision selection rule. See
the section "Parallel Development with Activities" for further details on
activities. When a workspace revision selection rule is used to perform revision
selection for a versioned resource: If the URL is to a checked out working
resource, then it is selected. Working resource can only be accessed through a
workspace. If the URL is to a versioned resource that is not checked out, 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
names, and to other resources to determine the revision containing their
contents.
A workspace revision selection rule can specify any number of revision labels,
activities, configurations, or the revision selector "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 with changes made in other activities. A
configuration matches a revision contained in that configuration. Latest matches
the latest revision based on the last modified time. See the section
"Configurations" for further details on configurations.
If a request is made and no workspace is specified, a default workspace
containing no activity and "latest" in the version selection rule is used.
Administrators can change the current activity and revision selection rule of
this default workspace to have such down-level client requests done in an
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, the server selects a
workspace and returns it in the checkout response. 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 workspaces
as checkout tokens to do so.
Revisions are checked out in the current activity of the workspace if any. When
the resource is checked back in, it remains visible in the workspace if the
workspace revision selection rule contains the current activity. In order to
prevent checked in revisions from becoming invisible in the workspace if
activities aren't used, a workspace may have a current label. This label is
automatically applied to any revision when it is checked in. If the versioned
resource already has a revision with this label, the label is moved to the new
revision. Putting this label in the workspace revision selection rule will
ensure that all checked in revisions are visible in the workspace.
Parallel 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 activities that
can be used to enable parallel development. These different activities can be
merged together at some later time in order to integrate the changes. 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. See the section "Merging" for
further details.
Simple parallel development can be accomplished without using activities. A
server may allow many checkouts of the same revision without using an activity.
The workspace merge conflict report is not available to detect conflicts
resulting from changes that were not made in the context of an activity. Client
applications are responsible for detecting and integrating the changes. In order
to prevent checked in revisions from becoming invisible, the workspace supports
a current label. The current label is automatically moved to any new revision
that is checked-in to that workspace. Two workspaces with different current
labels can work in parallel on the same versioned-resource, and then simplified
merging can be performed by adding both labels to the revision selection rule of
the workspace incorporating the changes done in other workspaces.
Configuration Management
A workspace represents a volatile set of revisions. Any new checkouts in that
workspace, changes to versioned resources
that affect the revision selected by the revision selection rule, or changes to
the revision selection rule itself, may result in the selection of different
revisions or working resources for versioned resources. A configuration is a
versionable resource that represents a consistent, immutable set of revisions. A
configuration contains a set of revisions, where a given versioned resource can
have at most one revision in a given configuration. A configuration cannot
contain a mutable revision because the semantics of configurations cannot be
guaranteed. Different revisions of a configuration can select different
revisions of
the same versioned resources, or can select revisions of different versioned
resources. A configuration may be used as a revision selector in a workspace
revision selection rule. A workspace whose version selection rule contains a
configuration will always return the same revisions as long as there are no
revisions checked out.
A revision may be added to a configuration by a specific label, or is the
revision may be selected by a given workspace. When a revision of a versioned
collection is added to a configuration, it, and recursively all its members are
added to the configuration. That is, a revision for the collection, and
recursively revisions of all its members are selected. This enables
configurations to maintain the state of namespaces defined by versioned
collections as well as the state defined by the contents and properties of
resources. Adding a revision to a configuration that already contains that
member replaces the selected revision.
The URL used to access a revision of a versioned resource in the context of a
label or workspace when the revision is added to a configuration is not retained
in the configuration. In order to access this revision at some later time, it is
necessary to add the configuration to the revision selection rule of a
workspace, and bind a name in the server's namespace to the versioned resource
corresponding to the desired revision. Then the server uses the URL binding to
access a versioned resource, and the workspace to select a particular revision
as specified by the configuration in the revision selection rule. This allows
flexibility in naming revisions in the context of how they are used. If the user
URL of the revision is important, then it is possible to retain this information
by putting a revision of the revision's parent collection in the configuration.
Configurations can depend on other configurations. The meaning of this
dependency is that when a configuration is used as a revision selector in a
workspace revision selection rule, its dependent configurations are also
implicitly included. Dependent configurations cannot have overlapping members.
A versioned collection has an associated baseline which is a distinguished,
versioned configuration containing the collection, and recursively, all its
members. A new revision of a versioned collection baseline is created by
baselining the collection. If a collection represents a component and its parts,
a baseline of a collection represents a particular configuration of that
component. Baselines provide a convenient means of accessing versions of a
configuration of a versioned collection and facilitate reuse by helping users
discover which configuration to use.
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 of 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.
As described in the section "Configurations", a versioned collection may have a
baseline which is a versioned configuration selecting a revision of the
versioned collection, and recursively revisions of all its members.
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 may
make their changes in the context of an activity. Changes to the same revision
must be done in separate activities or using no activity. 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 revisions 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 revision selection rule, and introduces merge 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.
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.
In summary, merging activities is simply adding the activities to the revision
selection rule of a workspace. The workspace can then produce the potential
revision conflicts by detecting activities that specify revisions on different
lines of descent of the same versioned resource. These conflicts are available
in the merge conflict report. Conflicts are resolved by merging the revisions
creating new working resources where the client suitable applies changes from
conflicting revisions. The merge is complete when the merge conflict report is
empty.
Controlling 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.