Internet Draft L. Dusseault Document: draft-dusseault-deltav-subset-00.txt Xythos Expires: April 2002 October 2001 DeltaV Subset for Simple Authoring Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. Abstract This document specifies a consistent profile or subset of the features from the DeltaV specification [DeltaV]. The subset is suitable for simple linear document versioning in a WebDAV [RFC2518] environment. The subset is intended to limit functionality in order to improve predictability and thus interoperability. If a server advertises support for this subset, then a client can interoperate with that server very easily due to its predictability. A server advertising support for this subset MUST also support DeltaV. Table of Contents 1 Overview.......................................................3 2 Introduction...................................................3 2.1 Definition of Simple Versioning.............................3 2.2 Requirements for Simple Versioning..........................5 Dusseault Expires April 2002 1 DeltaV Subset for Simple Authoring October 2001 2.3 Minimal Server Options:.....................................6 2.4 Unsupported DeltaV Features.................................6 3 Required Resources.............................................7 3.1 Version-Controlled Resources................................8 3.2 Versions....................................................8 3.3 Working Resources...........................................8 3.4 Version History Resources...................................8 4 Recommended Functionality......................................8 4.1 Deleting VCRs...............................................8 4.2 Turning Versioning Off......................................8 4.3 Deleting Versions...........................................9 5 Required Methods..............................................10 5.1 VERSION-CONTROL............................................10 5.2 CHECKOUT...................................................10 5.3 CHECKIN....................................................11 5.4 UNCHECKOUT.................................................11 5.5 REPORT.....................................................11 6 Required Properties...........................................12 6.1 DAV:comment................................................12 6.2 DAV:supported-method-set...................................12 6.3 DAV:supported-report-set...................................14 6.4 DAV:supported-live-property-set............................14 6.5 DAV:creator-displayname....................................15 6.6 DAV:checked-in.............................................15 6.7 DAV:checked-out............................................15 6.8 DAV:auto-version...........................................15 6.9 DAV:predecessor-set........................................16 6.10 DAV:successor-set..........................................16 6.11 DAV:checkout-set...........................................16 6.12 DAV:version-name...........................................17 6.13 DAV:auto-update............................................17 6.14 DAV:checkin-fork...........................................17 6.15 DAV:checkout-fork..........................................17 6.16 DAV:version-set............................................18 6.17 DAV:root-version...........................................18 6.18 DAV:version-history........................................18 7 Security Considerations.......................................18 8 References....................................................19 9 Author's Addresses............................................19 Dusseault Expires April 2002 2 DeltaV Subset for Simple Authoring October 2001 1 Overview DeltaV [DeltaV] is a very complete versioning specification for diverse environments. It has options to support a wide variety of versioning features ranging from simple to complex. It is capable of exposing a source code repository to source management clients, which typically have very extensive and complex versioning functionality requirements. The DeltaV specification presents a few challenges for simpler authoring software: - Server implementers may find it difficult to choose a limited subset of features that is sufficient and complete for simple versioning, yet is compliant with DeltaV. - Clients that are not primarily versioning applications may not wish to implement extensive code for handling all the DeltaV features, and thus will find it challenging to deal with servers that vary in what features and options are implemented. - Clients and servers both may have to expend a lot of research and thought to figure out what features to support to interoperate with a large number of other DeltaV implementations. This document attempts to improve interoperability for simple versioning in the following ways: - By setting aside some features which need not be implemented at all for clients or servers following this subset (e.g. merge, baseline, activity features) - By recommending limited options for features that are complex (e.g. only one value recommended for auto-versioning behavior) - By explaining and providing examples where helpful. - By explaining how to implement a non-forking server with DeltaV. The versioning model followed by this draft is unchanged from the DeltaV model. 2 Introduction 2.1 Definition of Simple Versioning Simple versioning systems are those that work with largely independent documents. This description includes user-oriented documents such as images, word processor documents, spreadsheets, and plain text files. This description does not include files that are strongly inter-related and that change frequently, such as the set of source code files that need to be compiled together to build a software program. The definition here is merely a matter of convenience in order to be able to draw a line; however, from looking at the versioning systems that exist, they do seem to fall into two categories on either side of that line. Dusseault Expires April 2002 3 DeltaV Subset for Simple Authoring October 2001 Systems that implement source code versioning have a number of requirements that are not necessarily requirements when source code isnÆt involved. Some of the differences: - Source code file versions relate to each other in very important ways. Thus, there may be a need for workspaces to group related files together while working on new versions, or baselines to group a bunch of versions together, or activities or version-controlled collections. In contrast, the dominant situation with regular document collaboration is that each document is stand-alone: although it relates to other documents, it doesnÆt have to be kept in strict compatibility with other documents in the same system. Although a few documentation tools link natural-language documents together, these tools and the documents they produce are rare compared to stand-alone natural-language documents. - Source code systems generally require multiple authors to be able to modify a file at the same time. Features like multiple working resources and/or activities are usually required. Also, source code systems may often be able to merge changes from multiple authors together because of the nature of files stored in those systems. In contrast, in simple document management situations, it's usually sufficient to limit authoring to one at a time, and it's rarely easy to merge documents together (imagine merging two sets of changes to one image together). Thus, both multiple working resources and merges are not required for simple document versioning. - Source code repositories are usually required to keep all old versions. It can be very important to be able to retrieve any archived version. In contrast, there are sometimes scenarios where itÆs very important to delete old versions, for legal purposes or for privacy. Note that DeltaV does allow versions to be deleted, but it also allows the server to forbid deleting versions, so clients may not be able to predict server behavior in this respect until trying it. - Interoperability with existing WebDAV clients like Office 2000 and Adobe authoring applications is of primary importance for document-oriented versioning servers. Source code versioning servers may not have to interoperate with those, but instead only have to interoperate with more special-purpose versioning clients (CVS client, Visual Source Safe client, subversion). - Forking is usually required in source control systems, but rarely required in simple document systems. Unlike source code files, when regular files need to diverge down two paths, they can almost always be copied and given two different names or locations. In summary, a simple document versioning system can implement less than half the features a complete source versioning system needs, Dusseault Expires April 2002 4 DeltaV Subset for Simple Authoring October 2001 yet satisfy 90% of the needs for authors of those documents. If this profile selects features carefully it can vastly reduce the complexity of versioning for simple document management clients and servers, yet still remain entirely compatible with DeltaV. 2.2 Requirements for Simple Versioning The following functionality is required in document versioning systems. - Interoperate with non-versioning clients - Turn versioning on for a resource - Turn versioning off for a resource (by deleting the VHR) - Find all versions - Support for checkout-in-place required for interoperability with non-versioning-aware clients. - Support for deleting versions - Global properties -- properties whose value applies to the entire version history, not just one version (these are supported on the VHR) As a result of these requirements, the following DeltaV features are required: - version-control - checkout-in-place - version-history The DeltaV feature "working-resource" is recommended as well, but optional. This specification defines an additional feature string "simple- deltav-subset", to be displayed in the OPTIONS response. This helps the client know if the server is going to behave predictably. If the server advertises "simple-deltav-subset" support, it must meet the following requirements: - MUST NOT have forks in the version history - MUST NOT allow UPDATE to make a version other than the latest version be the target version - MUST NOT allow versions to be checked out - MUST NOT have more than one working resource associated with a VCR - MUST NOT have more than one VCR associated with a VHR. - MUST support version-control, checkout-in-place, version- history features The OPTIONS response for a server supporting this specification may look like this: OPTIONS * HTTP/1.1 Host: subset.deltav.webdav.org Dusseault Expires April 2002 5 DeltaV Subset for Simple Authoring October 2001 HTTP/1.1 200 OK DAV: 1, 2, version-control, checkout-in-place, version-history, working-resource, simple-deltav-subset Allow: PUT, POST, HEAD, OPTIONS, GET, TRACE, DELETE, CONNECT, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK, VERSION-CONTROL, CHECKOUT, UNCHECKOUT, REPORT 2.3 Minimal Server Option Discovery Required This specification attempts to keep variation between server implementations to an absolute minimum in order to allow very simple client implementations to be written. There are very few options for variation between servers that support this specification. This means that the client may have to look in only a couple cases to see which way the server operates. - Checkout location: server can support in-place only, or both in-place and working resource. Support for both is there if the server supports this subset plus ôworking-resourceö in the DAV: header. - Auto-versioning: server can support checkin-when-unlocked or nothing. Client can check this on any VCR by looking at the value of the auto-versioning property. Of course, the server can also support advanced DeltaV features, such as LABEL. However, if support for advanced features means violating any of the requirements in the previous section, then the server cannot advertise support for "simple-deltav-subset" because it will not be able to meet the expectations of a simple subset client. 2.4 Unsupported DeltaV Features In addition to the unsupported packages (label, update, merge, workspace, version-history, baseline, activity, version-controlled- collection), these following features are explicitly not supported for this subset. An implementation is allowed to support them, but interoperability does not require them. a) UPDATE and current version In source control systems, UPDATE is used to get a Version- Controlled Resource to point to (represent) a version other than latest checked-in version. Document systems rarely need this functionality, and worse, it severely complicates many client operations as well as server implementations. Therefore the UPDATE method and functionality must not be supported on a server advertising support for this subset. This has the following simplifying consequences: - If the resource is checked in, the latest checked-in version is always the one visible in the Version-Controlled Resource. Dusseault Expires April 2002 6 DeltaV Subset for Simple Authoring October 2001 - Whenever the checkout is done it must be done on the VCR. If the intent is to create a working resource, it must be done with the ôapply-to-versionö flag. - Auto-update will be done whenever a working resource or checkout in-place is checked in. This means that the ôauto- updateö property on a working resource will always contain an href pointing to the VCR. Servers may refuse any CHECKIN where the auto-update value has not been set as above. - Only the latest version may be checked out. This makes it much easier to handle checkout-set: only the latest version can ever have a non-null value for checkout-set. That means the client only needs to check the latest version to see if itÆs checked out, rather than check every version. b) No Fork Support This profile does not include any forking support. This has the following simplifying consequences: - DAV:checkout-fork is ALWAYS forbidden - DAV:checkin-fork is ALWAYS forbidden - Only one checkout of any kind may be made. Only one working- resource can exist, and only if the resource isnÆt checked-out in-place. A resource may be checked out in-place only if no working-resource exists. - In order to find out if a resource is checked out, the client can simply look on the VCR for the DAV:checked-out property to see if there is an in-place checkout, and look at the latest version to see if there is a working resource checkout. In other words, a resource is checked out if either the checked- out property is set on the VCR or the checkout-set property is set on the HREF identified in the checked-in property of the VCR. 3 Required Resources In addition to regular WebDAV resources and collections, support for this DeltaV subset requires three additional types of resources: versions (a specific version of a resource), VCRs and Version History Resources (VHR). A server may also support working resources, which are a separate resource type. Since these are all separate resources, only one should be locked at a time; that is, for any given client LOCK request, the server should only lock the resource addressed with the URL, and not lock associated resources. That means the client can lock their VCR (to indicate to non-versioning clients that it is being edited) but not lock their Working Resource at the same time (in order to be able to send the Working Resource URL to another user and collaborate on the next version). Dusseault Expires April 2002 7 DeltaV Subset for Simple Authoring October 2001 3.1 Version-Controlled Resources Requirements: - VCRs MUST be lockable. - VCRs MUST support write operations because they must be compatible with non-versioning clients (including PROPPATCH, PUT). - VCRs SHOULD be deletable. 3.2 Versions Requirements: - Versions should not be lockable. - Versions MUST NOT support any write operation. - Versions SHOULD be deletable. 3.3 Working Resources Requirements: - WRs MUST be lockable, separately from VCRs, because they can be modified independently. - WRs MUST support write operations. Clients should not attempt to DELETE a working resource, in order to make it simpler for server implementations. Instead, a working resource can be removed by issuing an UNCHECKOUT. 3.4 Version History Resources Requirements: - VHRs SHOULD be lockable because they can be modified independently. - VHRs SHOULD support write operations. - VHRs SHOULD support PROPPATCH of custom properties. 4 Recommended Functionality 4.1 Deleting VCRs It should be possible to delete VCRs, because many document management systems require the ability to cleanup in order to free quota, remove obsolete documents, etc. Deleting a VCR should result in the cleanup of all resources associated with the VCR: the VHR, the working resources, and the versions. Of course if any of these is locked or the client is not authorized to delete them, the request can fail. 4.2 Turning Versioning Off Dusseault Expires April 2002 8 DeltaV Subset for Simple Authoring October 2001 The DeltaV specification is silent on how to turn versioning off for a Version-Controlled Resource (VCR). Although this is almost never done in source-control systems, it may easily be required in simple document management systems. Some evidence for this point of view is that existing document management systems have already implemented this feature. Thus, although the feature of turning versioning off should be optional, it would improve interoperability to define the mechanism by which it is done. One previously suggested mechanism is to COPY the VCR to a new location (which may create a new, unversioned resource) then DELETE the VCR. Finally, the new location is renamed to the original name with MOVE. This mechanism is inappropriate because it loses information on the original file: creation date, the name of the original creator, access logs, etc. This specification recommends rather to delete the VHR in order to turn the VCR into a non-versioned resource. This requires the server to allow deletion of VHRs in order to support this feature. It also requires the server to do cleanup: the VCR must be turned into an ordinary resource, with the properties that would be expected of an ordinary resource. For example, the "version- history", "checked-in", "auto-version", and "checked-out" properties must be removed from the VCR if present. Working resources associated with the VCR should be deleted. There are certainly circumstances where deleting the VHR should be forbidden: - The client is not authorized to perform this action - The VHR, VCR, or a working resource associated with the VCR is locked, and a lock-token was not provided or the client is not authorized to use the lock-token. - The server does not support this functionality 4.3 Deleting Versions Although DeltaV does not require servers to either allow or disallow the ability to delete versions, this specification recommends allowing versions to be deleted by clients with sufficient authorized permissions. When a version is deleted, the server must clean up so that the state of the resources is consistent. That means that the version must be deleted from any "predecessor-set" and "successor-set" property in which it appears, and replaced by a version which still exists. If the version is the first/root or the last/latest version, the cleanup may need to be a little different (the root-version property on the VHR must change), but it should still be possible to delete the version. The first/root version is replaced by the version that was created after it, the last/latest version is replaced by the version that was created before it. Dusseault Expires April 2002 9 DeltaV Subset for Simple Authoring October 2001 The last remaining version, which is both the root and the latest existing version, cannot be deleted. If the client finds itself in this situation and wishes to delete the last remaining version, it has two choices: - Delete the entire VCR. - Add a "dummy" version. Now the other version can be deleted and the dummy version becomes the last remaining version, also the root and latest existing version. This should not be necessary as long as the server supports deleting the entire VCR. 5 Required Methods For these methods, error handling is done exactly as specified by DeltaV. 5.1 VERSION-CONTROL The version-control method is required to turn versioning on, because in simple versioning systems typically not all documents are required to be versioned. In this subset, the VERSION-CONTROL method never needs a body. VERSION-CONTROL foo.doc HTTP/1.1 Host: server.com Full DeltaV clients may send XML bodies on VERSION-CONTROL requests (this is part of the Workspace feature). When a server receives a VERSION-CONTROL request that has a well-formed XML body, it should not reject the request (either with 400 Bad Request or 415 Unsupported Media Type). Another inappropriate response would be to simply ignore the body and successfully process the request -- because that would result in the client asking for one action and the server performing another. What the server must do is examine the XML body and find out if it's simply an empty "version-control" element or not. If it's an empty "version-control" element or contains XML elements not defined in DeltaV, then the server can successfully process the request (recall that RFC2518 specifies that unknown XML elements may be ignored). On the other hand, if the "version-control" element contains "version" elements, then the server should fail the request, and the most appropriate failure code is 501 Not Implemented. Note that a client should never send this request body to a server that does not support workspaces. 5.2 CHECKOUT In this subset, the checkout method can only be used to check out the tip node, or latest version. This is because forking and multiple checkouts are not part of simple versioning. (Note that it is possible to copy the contents of an older version to a working Dusseault Expires April 2002 10 DeltaV Subset for Simple Authoring October 2001 resource or in-place checkout, so itÆs still possible to work from the content of an older version). To do checkout in-place, no body is required: CHECKOUT foo.doc HTTP/1.1 Host: server.com:8080 To do checkout to a working resource, make the checkout request to a version URL instead of to the VCR URL. In this case, the ôapply-to- versionö flag is required, so a body is required for the CHECKOUT method. The ôfork-okö flag should not be present: CHECKOUT foo.doc.v1 HTTP/1.1 Host: server.com:8080 Content-type: text/xml Content-Length: xxx 5.3 CHECKIN In this subset, CHECKIN can be applied either to a VCR that is checked out in-place, or to a working resource. The check-in always fully checks in and updates the resource; that is, the resource does not remain checked out, and the version-controlled resource acquires the properties and content of the version just created. Because checkin only has one behavior, no body is required. CHECKIN foo.doc HTTP/1.1 Host: server.com:8080 5.4 UNCHECKOUT UNCHECKOUT works as defined in DeltaV. Note that UNCHECKOUT only works on checkout-in-place. In order to æuncheckoutÆ a working resource in a DeltaV compatible manner, the client should delete the working resource. If the client deletes a working resource, the server must restore the VCR and its versions to a consistent state so that some other user can check out the resource. That means at a minimum the ôchecked-outö property of the version that was checked out needs to be removed now. 5.5 REPORT Dusseault Expires April 2002 11 DeltaV Subset for Simple Authoring October 2001 The report method is supported because of the requirement to get a list of versions associated with a resource û the version-tree report provides this functionality. A good example of the REPORT method may be found in section 3.7 of the DeltaV specification. 6 Required Properties 6.1 DAV:comment Required: on all resources Writable: can be written except on checked-in versions The DAV:comment property is required on all WebDAV resources, including regular resources, collections, VCRs and versions. Final Draft 6.2 DAV:supported-method-set Required: on all resources Writable: protected The supported method set value is the same as the OPTIONS Allow header value. These are the recommended values for the resource types supported by this subset. Regular resource: Collection: Dusseault Expires April 2002 12 DeltaV Subset for Simple Authoring October 2001 Version-controlled resource: Version: Working Resource: Dusseault Expires April 2002 13 DeltaV Subset for Simple Authoring October 2001 6.3 DAV:supported-report-set Required on: All resources Writable: protected Since this subset only uses the version-tree report, servers only have to list that one report and only for VCRs and versions (but are free to support others). The recommended value for supported-report set depends on the resource type: Version-Controlled Resource or Version: All other resources: 6.4 DAV:supported-live-property-set Required on: all resources Writable: protected. Example: this example is for a regular, non-versioned resource, on a server supporting locking. Dusseault Expires April 2002 14 DeltaV Subset for Simple Authoring October 2001 6.5 DAV:creator-displayname Required on: all resources Writable: Fully writable except on checked-in versions. The DAV:creator-displayname property is required on all WebDAV resources, including regular resources, collections, VCRs and versions. It does not need to have a value. [!CDATA[John Doe]] 6.6 DAV:checked-in Required on: every checked-in VCR Writable: Protected. The DAV:checked in property is required on VCRs that are checked in. In this subset, the version URL value of the property is always the latest checked-in version. http://server.com/url-to-version 6.7 DAV:checked-out Required on: every checked-out VCR Writable: Protected. The DAV:checked-out property is required on VCRs that are checked out. In this subset, the version URL value is always the latest checked-in version. http://server.com/url-to-version 6.8 DAV:auto-version Required on: every VCR Writable: Protected. Although this property is required on every VCR, certain values are discouraged. One value is recommended. In this subset, the property MUST be protected, and should be the same for every resource in the repository. Dusseault Expires April 2002 15 DeltaV Subset for Simple Authoring October 2001 - No value: this is allowed. It indicates the server does not support auto-versioning at all. Non-versioning-aware clients then cannot modify version-controlled resources. - DAV:checkout-unlocked-checkin is encouraged because it has the best interaction with clients that lock and do auto-save: it produces only one new version for each editing session. The checkout is performed not when the LOCK request is received, but when the first PUT (or other write operation) is received. The checkin is performed when the UNLOCK is received. When clients that do not lock modify documents, the document is checked out and checked in again along with the write operation. - DAV:checkout-checkin is discouraged because the with clients that auto-save and are versioning-unaware, even if they lock the file during a session of editing, this behavior would produce too many versions. - DAV:checkout and DAV:locked-checkout are discouraged because they donÆt work with clients that are versioning-unaware. The user would have to go out of band to do the checkin û and they wonÆt know to. If forking is disallowed, this would prevent all other users from checking out. 6.9 DAV:predecessor-set Required on: every checked-out VCR and every version. Writable: Protected In this subset, DAV:predecessor-set contains only the URL of the version preceding this one. This is a direct consequence of taking the DeltaV definition for this property, then not supporting forking or update. http://server.com:8080/__V__1__foo.doc 6.10 DAV:successor-set Required on: every version. Writable: Protected. In this subset, DAV:successor-set contains only the URL of the version following this one. http://server.com:8080/__V__3__foo.doc 6.11 DAV:checkout-set Required on: the tip version (the latest checked-in version) if and only if it is checked out. Dusseault Expires April 2002 16 DeltaV Subset for Simple Authoring October 2001 Writable: Protected In this subset, DAV:checkout-set is either empty (there are no checkouts related to this version or this version-history) or has a single value. If the check-out is in-place, the URL in this property is the URL of the VCR. If the check-out is to a working resource, the URL in this property is the URL of the working resource. http://server.com:8080/__WR__foo.doc 6.12 DAV:version-name Required on: every version. Writable: Protected In this subset, version-name has the same definition as in DeltaV. 13 6.13 DAV:auto-update Required on: only working resources (if implemented) Writable: protected In this subset, the auto-update property on a working resource must always be set, and it must always contain the URL of the VCR associated with the working resource. http://server.com/foo.doc 6.14 DAV:checkin-fork Required on: all versions, working resource if implemented. Writable: protected Since this subset does not include forking, the value of checkin- fork is always forbidden. 6.15 DAV:checkout-fork Required on: all versions, working resource if implemented Writable: protected Since this subset does not include forking, the value of checkout- fork is always forbidden. Dusseault Expires April 2002 17 DeltaV Subset for Simple Authoring October 2001 6.16 DAV:version-set Required on: VHRs Writable: protected This property is fully defined in DeltaV and is unchanged in this subset. 6.17 DAV:root-version Required on: VHRs Writable: protected This property is fully defined in DeltaV and is unchanged in this subset. 6.18 DAV:version-history Required on: VCRs Writable: protected This property is fully defined in DeltaV and is unchanged in this subset. 7 Security Considerations This document has no new security considerations since it selects a subset of DeltaV. Dusseault Expires April 2002 18 DeltaV Subset for Simple Authoring October 2001 8 References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [DeltaV] Clemm, Geoffrey, Jim Amsden, Tim Ellison, Chris Kaler, Jim Whitehead, "Versioning Extensions to WebDAV", RFC TBD, October 2001. [RFC2518] Goland, Y., E. Whitehead, A. Faizi, S. Carter and D. Jensen, "HTTP Extensions for Distributed Authoring -- WebDAV", RFC2518, February 1999. 9 Author's Addresses Lisa Dusseault Xythos 77 Maiden Lane, Suite 200 Phone: 1-415-248-9004 San Francisco, CA, USA Email: lisa@xythos.com Dusseault Expires April 2002 19