From: firstname.lastname@example.org To: email@example.com Message-ID: <8525670C.0059F047.firstname.lastname@example.org> Date: Tue, 2 Feb 1999 11:14:52 -0500 Subject: WeDAV Versioning Summary After following the versioning and CM discussions the last couple of weeks, two things have become apparent. One is that our ideas and proposals have been complicated by listing lots of options, motivations, and issues making it difficult to understand, and two, perhaps we haven't been as clear as we could have been in describing the versioning semantics. In any case, I thought it might be a good idea to just summarize where I think we are so far as simply and completely as possible. Hopefully this will answer some questions, provide a clear starting point for next week's versioning meeting. I will attempt to summarize the semantics and rules that Geoff and I have been working on, and that have been discussed the last few weeks on xml-dav-versioning. I won't in this document 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, DMS, and CM 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. Creating Versioned Resources A resource can be put under version control by checking it in. Checking in a resource creates a versioned resource and sets its initial revision to the resource. A checked in revision cannot be modified by anyone at any time. 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. 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 checkout makes the revision a working resource, and allows the revision to be updated in place without creating a new revision. Any previous contents of the revision are lost. A mutable revision can also be checked out creating a new revision if the user wants to retain the previous revision. If the revision is immutable, a checkout must create a new revision. Servers may choose to not allow revisions to be checked in as mutable, or they may not allow a revision to be checked out 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. 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 parallel thread of development. Servers that don't support parallel development only support one activity. 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. 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 resource URL and a version label. However, versioned resources are usually accessed using a simple 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 supporting relative ULRs and DAV level-2 clients that are not versioning aware. A workspace contains a current activity, a merge activity, and a revision selection rule. Revisions are selected using the following rules in order: 1) if there is a checked out revision, then it is selected. else 2) if there is a revision that is checked in under the current activity, then it is selected, else 3) if the resource is a member of any activity in the process of being merged into this workspace, then it is selected, else 4) finally, 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 versioned resources, 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 matching is found. Any subsequent potential matches are ignored. The first three rules above are just implied components of the workspace revision selection rule. They are called out separately as they are fixed by the server. If a request is made and no workspace is specified, a default workspace containing activity named "mainline", and "latest" in the version selection rule is used. 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. A workspace whose version selection rule contains a configuration will always return the same revisions as long as there are no revisions checked out and nothing in the current activity. Versioned Collections A collection contains a set of members. For versioned collections, the members are 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 the 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 or merged from, and a successor relationship with revisions that were checked out from it. Mutable revisions are related to their predecessor through a was-derived-from relationship. Immutable revisions are related to their predecessor through an is-derived-from relationship. The revision history of a versioned resource can include either or both of these relationships. 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. 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. 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 an additional 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. Only one activity can be merged at a time. 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.