INTERNET DRAFT Christopher Kaler, Microsoft Expires January 31, 1999 08/06/98 Versioning Extensions to WebDAV Status of this Memo This document is an Internet-Draft. 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 made obsolete 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". To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Please send comments to the Distributed Authoring and Versioning (WEBDAV) working group at , which may be joined by sending a message with subject "subscribe" to . Discussions of the WEBDAV working group are archived at . Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. Abstract This document describes a set of methods, headers, and properties that extend the HTTP and WebDAV protocols to support versioning and variant authoring of Web resources. Operations are provided to perform both basic versioning and parallel versioning. This document is a stawman proposal and does not have the endorsement of the WebDAV working group authors. Contents 1 Introduction 4 1.1 Relationship to DAV 4 1.2 Terms 4 1.3 Notational Conventions 4 1.4 Definitions 4 1.4.1 Resource 4 1.4.2 Resource Version 4 1.4.3 Project 4 1.4.4 Line of effort 5 1.4.5 Excluded Areas 5 2 Scenarios 5 2.1 Document Versioning 5 2.2 Collection Versioning 5 2.3 Parallel Versioning 5 2.4 Isolated Authoring 5 2.5 Multi-Language Authoring 5 3 Requirements 6 3.1 Functional 6 3.2 Performance 6 3.3 Easy 6 3.4 Portable 6 3.5 Atomic 6 3.6 Extensible 6 3.7 Versioning Granularity 6 3.8 Language Variants 6 4 Versioning Overview 6 4.1 Basic Versioning Operations 7 4.2 Configuration Management 7 4.3 Sharing 8 4.4 Resolution Queues 8 4.5 Graphs 9 5 Language Variants Overview 9 6 Versioning Extensions 9 6.1 Discovery of Versioning Support 9 6.2 Basic Operations 10 6.2.1 Simple Check-Out and Check-In 10 6.2.2 Undo Check-Out 14 6.2.3 Enumeration of Check-Outs 14 6.2.4 Grouped Changes 14 6.3 Branching 15 6.4 Discovering the Branch Namespace 15 6.4.1 Creating Branches 16 6.4.2 Branch Properties 17 6.4.3 Deleting Branches 17 6.4.4 Default Branch 17 6.4.5 Derivation 17 6.4.6 Branch and resource Graphs 18 6.4.7 Modifying Branches 20 6.4.8 Synchronizing Branches 21 6.4.9 Setting Current Versions 21 6.4.10 Merging Branches 22 6.4.11 Purging Branches 22 6.5 Branch Discovery 23 6.6 Branch Check-Ins 23 6.7 Sharing 24 6.8 Resolution Queues 24 6.8.1 Discovering Resolution Items 24 6.8.2 Deleting Resolution Items 25 6.9 Miscellaneous 26 6.9.1 Destroy 26 6.9.2 Keyword Expansion 26 7 Language Variant Extensions 27 7.1 Resource Properties 27 7.2 Header Extensions 27 7.3 Default Variant 27 8 Internationalization Considerations 28 9 IANA Considerations 28 10 Security Considerations 28 11 XML Element Definitions 28 12 References 28 13 Author’s Address 28 1 Introduction The development of Web applications and content is stronger than ever. As this arena has grown, so has the need for tools and technologies that are commonplace in non-Web environments. This includes tracking and retrieving change history, supporting both collaborative and parallel efforts. This document describes extensions to the WebDAV distributed authoring protocol [WebDAV], which is itself an extension of the HTTP 1.1 protocol [RFC2068], for manipulating versioned resources and parallel versioning efforts. This document represents a similar but alternative model to that proposed in [White]. Note that this document does not address the variant notion proposed in [White] for handling international versioning. 1.1 Relationship to DAV This document describes a set of extensions to the currently proposed [WebDAV] specification to enable version management. 1.2 Terms This draft uses the terms defined in [RFC2068] and [WebDAV]. 1.3 Notational Conventions Since this document describes a set of extensions to the HTTP/1.1 protocol, the augmented BNF used herein to describe protocol elements is exactly the same as described in section 2.1 of [RFC2068]. Since this augmented BNF uses the basic production rules provided in section 2.2 of [RFC2068], these rules apply to this document as well. 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 [RFC2119]. 1.4 Definitions To ensure that terminology is consistent, this section describes several key objects referenced in this document. 1.4.1 Resource A resource is an object in the namespace that is referred to by a URI as defined in [WebDAV]. Resources include documents, collections, etc. 1.4.2 Resource Version A resource version refers to a specific version of a resource. All resource versions can be referred to by a URI and are therefore resources themselves. 1.4.3 Project A project refers to a collection of resources that have a common theme. Projects are really just containers so they are synonymous with collection resources. The project term is defined here because it is often used when discussing versioning. Example projects include my application manuals and my application sources. 1.4.4 Line of effort A line of effort refers to a sequence of changes towards a specific goal. For example, Beta1, or V2 or V3.1a. Lines of effort may have special relationships. For example, V2 is typically based on V1. It is also possible that lines of effort are unrelated. 1.4.5 Excluded Areas The following areas are omitted from this document as other drafts are addressing them: - Searching - Security 2 Scenarios This section describes several key scenarios driving versioning requirements. 2.1 Document Versioning Dick is working on several new chapters for a document. He reserves the files and obtains versions to make edits. When he is done, he initiates a check-in of all files in a transacted context so that he maintains consistency in his archive. 2.2 Collection Versioning While Dick is making changes he decides to re-organize the project and renames collections, creates new collections, and moves documents around between collections. This is all versioned so that Dick can revert back to a previous version of the project and have the correct collections and collection members. Note that namespace versioning allows namespace restoration. This is important because documents often have links to each other which, if not restored properly, could result in broken links. 2.3 Parallel Versioning Jane works with Dick, however, she works on the next version of Dick’s product. A separate version has been created for Jane’s work, which is based on Dick’s current work. This means that while Jane is changing files in one area, she can automatically see the changes Dick is making in his version of the document. 2.4 Isolated Authoring Ted and Alice work on different areas of the same project. Ted has a large task and wants to make changes without anyone else being affected until he is done. Ted makes his changes in isolation from the rest of the team and publishes them when he is done. Alice tends to work on small changes in an isolated area of the project, but likes to keep track of what everyone else in her team is doing. So she keeps herself isolated from the team, but synchronizes herself with the current team versions every other day. 2.5 Multi-Language Authoring Jack and Jill are writing a set of Web pages that describe their company’s products. Jack is responsible for the English version of the documents and Jill is responsible for the German version. Jill creates the initial version of the pages in German and Jack translates them one-by-one to English. Clients browsing their Web site can request either language variant. 3 Requirements This section identifies key requirements for WebDAV versioning extensions. 3.1 Functional The protocol MUST provide support for standard versioning functions such as check-out, check-in, etc. 3.2 Performance The protocol MUST be implementable in a performant manner. That is, the protocol SHOULD be defined with implementation performance as a consideration and SHOULDN’T require multiple round-trips for common operations. 3.3 Easy The protocol SHOULD make it easy for clients to add versioning support. 3.4 Portable The protocol MUST be implementable by different companies, on different platforms, with different versioning styles (e.g., document vs source management) and targets (e.g., text vs media). 3.5 Atomic The protocol MUST provide the ability to request version-related operations in a transactional context. However, it is NOT required for every server to support transactions. 3.6 Extensible The versioning specification MUST allow for protocol extensions where it makes sense. 3.7 Versioning Granularity The versioning specification MUST allow for all resources (including collections) to be versioned. As well, clients SHOULD be allowed to edit a resource without implicitly creating a new version. 3.8 Language Variants The versioning specification MUST allow for language variants of resources. Access to these variants MUST be easy. 4 Versioning Overview This section presents an overview of traditional versioning concepts as well as some new concepts that are introduced in this specification. 4.1 Basic Versioning Operations There are several operations that are considered basic to versioning: check-out, check-in, undo check-in or check-out, enumeration of check-outs, and enumeration of check-ins (history). Although the semantics can vary, most versioning systems support the notion of indicating intent to modify a document and then submission of the modified version. Typically this involves some form of locking (either shared or exclusive). As well, many systems support the ability to cancel a check-out or undo a recent check-in. These options are available to the owner or to the Administrator. Users can generally enumerate the current check-outs although they may not be able to determine the user in all cases. Likewise, users can review check-ins to see the change history. Most systems allow users to select different versions from the change history and present a comparison of the versions. It is important to note that everything is versioned. For example, when a property on a resource is changed, a new version of the resource is created. Likewise, when the contents of a collection change, a new version of the collection is created. However, some clients may not wish to have new versions automatically created. For example, they are working on a version and want to write the changes to the store and update them. New versions are created on request, not automatically (note that the default behavior is actually up to the store). It may be the case that down-level clients want to version resources they update, but have limited knowledge of versioning. These clients want to be able to update the resource and have it automatically versioned. 4.2 Configuration Management Many versioning systems provide branching and merging as a mechanism for creating variations of a document or for making changes in parallel. This specification introduces the notion of a Branch. A Branch is a branch at a project level and can contain variations of multiple documents. For example, if your project is a set of manuals for a product, you may have a V1 Branch, a V1.1 Branch, and a V2 Branch. Branches represent lines of effort or what is often referred to as configuration management. So how are Branches different from versioned resources? Branches differ in several key ways: (a) they are not part of the namespace, (b) they can include inheritance relationships, and (c) they distinguish versioning at all levels. For many Web projects, links must remain constant even when working on multiple versions of the project. By factoring the current Branch out of the URI, the need to fix-up links in multi-version environments is eliminated. Branches are derived from other Branches. In the example above, V2 is derived from V1.1, which is derived from V1. This relationship allows users to control the flow of changes down the chain. For example, V1.1 was created late in the cycle for V1. Consequently, they established the V1.1 Branch so that any changes to V1 would be automatically added to V1.1. Later, V2 was created for a new revision of the product. In this case V2 conditionally inherits from V1.1. That is, the owner of V2 is notified of changes to V1.1 and may choose to accept or decline the changes. The set of Branch derivation relationships includes: - Inherit changes automatically - Notify of changes - Based on current version - Based on current version when Branch was created - Based on latest version as of a specific time In some ways Branches are similar to a versioned collection. However, the scope of change is a key difference. In a versioned collection, if you change the collection, it is versioned. However, if the collection contains a collection and you change something in the contained collection, the outer collection is not versioned. Branches represent an alternate view of the namespace. There are several key operations that are performed on Branches: - Rename (Move) - change the name of the Branch - Delete - eliminate the Branch - Branch - create a new Branch based on the Branch - Synchronize - synchronize updates from derived-from Branches into this Branch - Set Default - set the default version of a document within the Branch Many systems have the notion of a label. This is a mechanism for marking a document at a specific version. Branches provide this functionality by allowing users to create a derived Branch that will never change. It is important to note that there can be namespace changes between Branches. For example, V2 may be based on V1, but the organization of the information may be changed. Branches need to track the resources even if the namespace changes. 4.3 Sharing It is common to share documents across projects. For example, you might have a Trademark page that is common to all of your manuals. Sharing can take two forms: full and regulated. Full sharing means that the same document exists in multiple places. Regulated sharing means that specific versions of a document are shared to multiple places. Regulated sharing can be performed using branches. 4.4 Resolution Queues There are times when an operation on the server creates a situation that requires manual intervention for resolution. For example, Dick checks in a change to his Branch. Jane’s Branch inherits from Dick’s Branch. However, Dick’s change conflicts with a change Jane made in here Branch. For these situations, the server maintains a queue of actions that need to be resolved. Clients can query and resolve the actions. The identified actions are: - Change occurred in derived-from Branch, do you want the change? - Conflicting change occurred in derived-from Branch, you must merge the changes. - Update has been made to a shared object, do you want the change? 4.5 Graphs When versions of documents are created, there is an implicit graph representing the history of the document. In systems that allow branching and merging, this graph can be an arbitrary directed acyclic graph. With the introduction of Branches, there are actually several graphs: the document versions, the branch derivations, the document derivations, and the Branch merge points. Because Branches are where deviations and merges take place, document version graphs are simple linear (history) lists. This facilitates many UI optimizations for clients as well as a simpler model for end-users. Branches on the other hand are directed acyclic graphs. Each arc in the graph indicates "is derived from" and has an associated property indicating the type of derivation (static, dynamic, conditional, etc.). Document derivation graphs represent the history of a document across all Branches. This too is a directed acyclic graph. The Branch merge graph is a directed acyclic graph representing not only the derivations of Branches, but also the merge points for Branches. 5 Language Variants Overview Branches can provide the ability to have alternate variants of the branch. This means that a branch can have multiple instances of any resource where each instance is associated with a variant. The typical use of variants is to support languages. For example, the Beta1 branch contains the documentation for Beta1. The Branch has English and German variants. Functionally they are exactly the same; however, the content of a document resource may vary. If a resource is renamed or the namespace is altered in any way, the change is reflected in all variants. The server maintains variants of the contents of a document resource. There is no requirement that different variants be synchronized. That is, if the English variant is edited, its content may be out of sync with the German variant. The server is not responsible for correlating this information, simply tracking the relationship. 6 Versioning Extensions The following sections describe the proposed enhancements to [WebDAV] to support versioning. 6.1 Discovery of Versioning Support Clients can use the OPTIONS verb to discover if servers support versioning semantics. OPTIONS * HTTP/1.1 Host: www.foobar.com Content-Length: 0 HTTP/1.1 200 OK Date: Wed, 05 Aug 1998 00:39:27 GMT Accept-Ranges: none Cache-Control: private Dav: 1, 2 Allow: OPTIONS, TRACE, GET, HEAD, DELETE, COPY, MOVE, PROPFIND, PROPPATCH, MKCOL, LOCK, UNLOCK Content-Length: 0 Public: OPTIONS, TRACE, GET, HEAD, DELETE, PUT, POST, COPY, MOVE, MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK Allow-Extension: DAV:versioning Public-Extension: DAV:versioning 6.2 Basic Operations This section describes the enhancements to support basic version control functions. 6.2.1 Simple Check-Out and Check-In In most version control systems the flow of changes is essentially the following: 1. Mark intent to modify the resource 2. Get the resource 3. Change it 4. Replace the resource 5. Remove intent marker The [WebDAV] protocol already provides mechanisms for doing this, so versioning should tightly integrate with these mechanisms: 1. LOCK resource 2. GET resource 3. Change it 4. PUT resource 5. UNLOCK resource In order to make this simple process work for versioning, there are several small extensions that must be added to [WebDAV]. 6.2.1.1 LOCK/UNLOCK Extensions The following sections detail extensions to the LOCK method. 6.2.1.1.1 Lock Comment The LOCK/UNLOCK are serving two purposes: to establish protection on the resource and to mark the intent of changes. This draft proposes to merge the two actions by allowing a comment to be added to the LOCK/UNLOCK methods. The check-out/check-in comment would be indicated as part of the lock/unlock request by having an optional XML tag. The DAV:lockcomment tag is added to the existing DAV: DTDs. Support for this tag MUST be provided. ... Update the Foo algorithm http://www.microsoft.com/ckaler To support versioning, the server MUST support locking. As well, the server MUST support advisory locks (i.e., Shared). The value of DAV:lockcomment is a string. 6.2.1.1.2 Check-Out Attributes Some systems also track the local destination of checkout requests. To enable this tracking, the client can advise this information (if known) by including another tag in the lock request. The DAV:user and DAV:localresource tags are optional and their value is opaque and only understood by the client. Support for these tags is optional. ... Update the Foo algorithm ckaler file:c:\foo\working http://www.microsoft.com/ckaler 6.2.1.1.3 Discovery Locks MUST be discoverable using DAV:lockdiscovery via PROPFIND. As well, this SHOULD support the following qualifier tags (possibly combined) within DAV:lockdiscovery to refine the lock space that is enumerated: - DAV:since and DAV:before tags to allow clients to limit discovery to locks taken during the specified time range - DAV:user to allow discovery based on the owner of the lock. The value is any legal URI. - DAV:localresource to allow discovery based on the output working folder - DAV:branch to allow discovery by branch - DAV:resource to allow discovery by resource 6.2.1.2 Identifying Specific Versions To identify a specific version of a resource, the Base-Version and Base-Branch header tags can be specified in the header. GET /foo/bar.htm HTTP/1.1 Host: www.foobar.com Base-Branch: http://www.foobar.com/XEEUS44932 Base-Version: The Base-Branch header tag identifies a specific branch (explained later) to scope the request. The Base-Version header tag can be any of the following: - A specific version identifier - Default to indicate the default version of the resource - Default-# to indicate a previous version from the default version Sometimes clients need to identify a specific version by time. For example, the current version as of Monday at 11:00 am. To do this, the Base-Version tag can use the ISO 8601 date format. 6.2.1.3 Versioning Collections Collections are treated the same as all other resources: when it is modified, a new version is created. This includes changes via PUT or PROPPATCH. Like operations on non-collection resources, clients can request to overwrite the existing resource using New-Version:F (see below), but servers reserve the right to force versioning. 6.2.1.4 Versioning Headers To better aid clients, the Base-Branch and Base-Version header tags MUST be returned from the GET and PUT methods if the headers were usedin the GET or PUT request. For GET, this allows clients to understand exactly which branch/version was returned. For PUT, this allows clients to understand what branch/version was associated with the PUT. GET /foo/bar.htm HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx HTTP/1.1 Base-Branch: http://www.foobar.com/XEEUS44932 Base-Version: Content-Length: xxx Content-Type: ... 6.2.1.5 Resource Property Extensions The following properties are added to all resources using the "DAV:" namespace and MUST be supported: - DAV:isversioned - 0/1 to indicate if the resource is versionable. Note that servers can implement this as a read-only property. - DAV:autoversion - 0/1 to indicate if the resource is automatically versioned when modified. Note that servers can implement this as a read-only property. - DAV:baseversion - This is a read-only property that identifies the version of a resource. - DAV:versionguid - This is a read-only property that returns a globally unique identifier for this specific version of the resource. Every version of a resource will have a separate versionguid. - DAV:resourceguid - This is a read-only property that returns a globally unique identifier for every unique resource independent of versions. That is, all versions of the resource have the same DAV:resourceguid. - DAV:previousversion - This is a read-only property that returns the URI for the previous version of the resource. An empty value indicates that there are no previous versions. Note that this could be a multi-valued property. If there are multiple versions, each is returned in a separate DAV:previousversion tag. - DAV:nextversion - This is a read-only property that returns the URI for the next version of the resource. An empty value indicates that there is no next version. 6.2.1.6 Handling Intermediate Changes It is possible for two different clients to PUT changes to the same resource when exclusive locking is not used. There are two approaches to resolving this issue: define that last one wins, or require the last change to merge with the earlier change. For the first outcome, no changes are required. When the resource is PUT, the previous version is replaced with the new version. To enable clients to support the merge requirement, the client can include a base-version qualifier in the header. This indicates the version the changes are based on and the server can refuse the PUT if that is not the current version (and it cannot automatically merge). Servers SHOULD support base-version on PUT requests. PUT /foo/bar.htm HTTP/1.1 Host: www.foobar.com Base-Version: ... 6.2.1.7 PUT Extensions The following sections detail extensions to the PUT method. 6.2.1.7.1 The New-Version Header It is possible that clients may wish to modify a resource several times before creating a new resource. To do this, they request that the server overwrite the resource rather than versioning it by including the New-Version header tag in the header. The example below illustrates a PUT request to overwrite rather than version. PUT /foo/bar.htm HTTP/1.1 Host: www.microsoft.com New-Version: F ... The New-Version qualifier can be used to request a new version be created (T), or to overwrite an existing version (F). If a server does not honor the New-Version header, then it MUST not succeed with a 200 level status code. Note that once a newer version of a resource is created, earlier version CANNOT be overwritten. 6.2.1.8 COPY Extensions Clients may need to copy resources from one branch to another. This is done using the Base-Branch, Base-Version, and Target-Branch header tags. Copying of both branches and contains is supported. Servers SHOULD support these COPY extensions. COPY /foo/bar.cpp HTTP/1.1 Host: www.foo.bar Destination: /foo/bar.cpp Depth: infinity Base-Branch: http://www.foobar.com/XEEUS44932 Target-Branch: http://www.foobar.com/XJ5F99934 Content-Type: text/xml Content-Length: xxx 6.2.1.9 Summary This approach to basic check-out and check-in greatly simplifies the client processing for versioning resources. This also has the added benefit of allowing down-level clients to create and modify resources without any implicit knowledge of versioning. Downlevel clients and use GET/PUT to operate against a version store and implicitly have new versions created. Smarter clients can use LOCK/UNLOCK to reserve resources. Another implication is that all changes to a resource, including PROPPATCH can cause a new version to be created unless the client requests an overwrite (and the server accepts it). This is desirable because the resource is being changed. Servers MUST associate the lock information with the version history if the resource is locked. 6.2.2 Undo Check-Out It is often desirable to cancel a check-out without updating the resource. To cancel a check-out, clients need only remove their LOCK with an UNLOCK request. Servers MUST provide this support. Note that this does not rollback changes, it simply releases the lock. 6.2.3 Enumeration of Check-Outs Clients can enumerate the active check-outs on a resource by discovering its active locks via DAV:lockdiscovery. Note that security restrictions may prevent clients from being able to identify the owner of a lock, however, the client must be able to discover that existing locks exist. 6.2.4 Grouped Changes Clients may desire the ability to track a set of changes as a unit. This allows semantic grouping changes as well as the ability operate on the entire collection of changes. When a client versions a resource (e.g. PROPPATCH, PUT, COPY, MOVE, ...), the return header includes a resource for the change. Clients can use this identifier on subsequent changes (e.g. PROPPATCH, PUT, COPY, MOVE, ...) to allow the server to correlate the changes. If a client specifies a correlation identifier using Checkin-Token that was not returned by the server, the server may fail with 412. The correlation resource can then be used with PROPFIND, PROPPATCH, DELETE, and COPY. PUT /foo/bar.htm HTTP/1.1 Host: www.foobar.com Content-Type: text/html Content-Length: xxxx ... HTTP/1.1 200 OK Checkin-Token: http://www.foobar.com/ci/DFDF3293289 Content-Length: 0 PUT /foo/bing.htm HTTP/1.1 Host: www.foobar.com Checkin-Token: http://www.foobar.com/ci/DFDF3293289 Content-Type: text/html Content-Length: xxxx ... HTTP/1.1 200 OK Checkin-Token: http://www.foobar.com/ci/DFDF3293289 Servers SHOULD support the Checkin-Token, but are not required to do so. 6.3 Branching To satisfy the requirements of parallel development, branches are introduced. Using branches, clients can manipulate resources at a project level. 6.4 Discovering the Branch Namespace Clients can discover the branching namespace of a server by examining the DAV:branchnamespace property. The value off this property is a URI that identifies a namespace against which the branch operations are performed. The value is defined by the server and is read-only. The examples below assume a branch namespace of "/bn/" 6.4.1 Creating Branches Clients can create new branches by using the MKCOL method against the branch namespace. This requests the server to create a new branch and the id is returned if the creation is successful. When a branch is created, special tags can be used to define the characteristics and relationships (which branches it is derived from) for the branch. The following table enumerates these tags. Tag Description xxx This tag allows the client to specify an href to identify another branch from which thisnew branch is to be derived. Auto The branch automatically inherits changes from its derived-from branch. Manual The branch inherits changes from its derived-from branch, but they are not automatically inserted into the branch. None The branch is a snapshot of the current versions in the derived-from branch. There is no inheritance of changes. xxx The branch is based on the current versions in the derived-from branch at the indicated time. MKCOL /bn/x HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx http://www.foobar.com/DDEJRJ445 Auto HTTP/1.1 201 Created Location: http://www.foobar.com/bn/RYURUS99009 Content-Length: 0 It should be noted that a branch is not required to be derived from another branch. In this case, the new branch is empty. This support MUST be provided if branches are supported. 6.4.2 Branch Properties The standard PROPFIND and PROPPATCH methods can be used with the branch id to get and set properties on a branch. Servers MUST provide branch properties if branches are supported. 6.4.3 Deleting Branches Branches are deleted by issuing DELETE requests and specifying the branch identifier. This support MUST be provided if branches are supported. DELETE /bn/RYURUS99009 HTTP/1.1 Host: www.foobar.com 6.4.4 Default Branch Clients can establish the default Branch the server uses (the Branch to use if a client doesn’t request one) using the DAV:defbranch tag with the PROPPATCH method. This support MUST be provided if branches are supported. PROPPATCH /bn/ HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx /bn/RYURUS99009 6.4.5 Derivation Clients are generally responsible for handling merges of sources from one Branch to another. If the client desires the server to track this information, it must be passed in a Derived-From header tag specified with PUTs. This header tag allows the client to indicate the Branch (or Branches) that the current put is derived from. PUT /foo/bar.htm HTTP/1.1 Host: www.microsoft.com Derived-From: http://www.foobar.com/DIRI343445,DAV:DFSFE334492 ... The value of Derived-From is a list of Branch,Version pairs that represent previous versions. Clients are not required to use the Derived-From header tag. Servers SHOULD support Derived-From. Servers SHOULD implement this support, but it is not required. 6.4.6 Branch and resource Graphs Clients often desire the ability to obtain history information about branches and resources. This protocol defines a method for obtaining this information by using the PROPFIND method. 6.4.6.1 Graph Discovery The DAV:enumgraphs tag is used to discover the types of graphs that are supported by a server on a given branch. Clients should obtain this property from the branch. PROPFIND /bn/FHJRH3994 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx TBD - show results This support MUST be provided if branches are supported. 6.4.6.2 Version History Clients can enumerate the history (check-ins) of a resource by requesting its version history graph. This returns an XML document representing the history of the object. Clients can also request that specific properties for each version be returned. PROPFIND /foo/bar.doc HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx ... This returns the version history for the specified resource. For each version, the properties identified by "..." are returned. Note that a single server may not have all of the version history for a document. In this case, the server should insert the tag. Clients can then request additional history from the identified server. This support MUST be provided if branches are supported. 6.4.6.3 Branch Derivation Graph Clients can easily obtain the derivation graph for a branch using PROPFIND. The graph is returned as a set of structured XML tags for easy parsing. Clients can also request that specific properties for each version be returned. PROPFIND /bn/RYURUS99009 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx ... TBD - show the XML that is returned This returns the derivation for the specified branch. For each branch, the properties identified by "..." are returned. This support MUST be provided if branches are supported. 6.4.6.4 Branch Merge Graph Clients can easily obtain the merge graph for a branch using PROPFIND. The graph is returned as a set of structured XML tags for easy parsing. Clients can also request that specific properties for each version be returned. PROPFIND /bn/RYURUS99009 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx ... TBD - show the XML that is returned This returns the merge graph for the specified branch. For each branch, the properties identified by "..." are returned. Servers SHOULD support this property, but it is not required. 6.4.6.5 Resource Version Graph Clients can easily obtain the version graph (history of a resource across all branches) for a resource using PROPFIND. The graph is returned as a set of structured XML tags for easy parsing. Clients can also request that specific properties for each version be returned. PROPFIND /foo/bar.doc HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx ... TBD - show the XML that is returned (note that each version indicates the branch in which it was changed). This returns the resource version graph for the specified resource. For each resource, the properties identified by "..." are returned. Servers SHOULD support this property, but it is not required. 6.4.7 Modifying Branches There are times when the attributes and relationships of a branch must be changed. These properties are changed via PROPPATCH. Servers SHOULD support this operation, but are not required to do so. PROPPATCH /bn/RYURUS99009 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx http://www.foobar.com/bn/DDEJRJ445 Manual 6.4.8 Synchronizing Branches In some scenarios, clients are working on separate branches to keep themselves isolated from other team members. However, they occasionally need to synchronize their branch with the derived-from branches so that they don’t get too far out of synchronization. This is done by using the DAV:syncbranch tag in a COPY request. Note that synchronization may result in merge conflicts that need to be resolved. These conflicts are recorded in the resolution queue for the branch. COPY /bn/ZZURTU99009 HTTP/1.1 Host: www.foobar.com Destination: /bn/RYURUS99009 Content-Type: text/xml Content-Length: xxxx TBD - show resultant XML Servers SHOULD support this operation, but are not required to do so. 6.4.9 Setting Current Versions Each branch maintains the notion of a current version of every resource. This version is used if the client doesn’t specify a specific version. This operation is performed using the DAV:setcurrent tag with the PROPPATCH method. Clients set this property on a resource specifying the branch. The result is that the version is made the current version in the specified branch. It should be noted that the current version is the latest version. If a client desires to work on a new version, possibly creating multiple versions that are not accessed by default, they should utilize a branch. When new versions are added, they automatically become the current version. However, there are times when a client wants to make an older version the current version. To do this, the client issues a DAV:setcurrent tag on the branch root. The DAV:setcurrent tag is also used to undelete and item if the server doesn’t permanently destroy items when they are deleted. PROPPATCH /bn/FISIE99009 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx DAV:FHFH4593 If a server supports branches, then it MUST support this operation. 6.4.10 Merging Branches Branches are often used to isolate team members while they are working. When they complete their tasks, they often want to merge their changes from their isolated Branch to a shared Branch. This is often referred to as promoting a change. This operation is performed using the DAV:merge tag with the COPY method. Clients can request that a single resource be merged or that all changed resources in the branch be merged. Merging Branches may result in merge conflicts. Clients can choose whether or not to fail the operation if there is a conflict. If the client requests not to fail, then the server will create an entry in the target Branch’s resolution queue. Note that this is only a request and servers can choose to fail merges if there are conflicts. COPY /bn/RYURUS99009 HTTP/1.1 Host: www.foobar.com Desitnation: http://www.foobar.com/bn/DFKE34934 Content-Type: text/xml Content-Length: xxxx /foo/bar.htm Servers SHOULD support this operation, but are not required to do so. 6.4.11 Purging Branches Within a Branch, all versions of resources are maintained. However, there are times when the owner of a Branch wants to eliminate all of the intermediate versions of a resource or set of resources. That is, only keep the latest version or latest n versions. This operation is performed using the purge tag with the DELETE method. The DAV:purge tag can be specified at the branch level to effect all resources or at the resource level to effect a single resource. The keep parameter can be specified to indicate the number of versions to keep. The default value for keep is one. DELETE /bn/RYURUS99009 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx /foo/bar.htm3 Servers SHOULD support this operation, but are not required to do so. 6.5 Branch Discovery Clients can discover the known Branches using the DAV:enumbranches. The basebranch, before, and after tags can be used to qualify the discovery based on parent branch and creation date. This is defined using the PROPFIND method. PROPFIND /bn/RYURUS99009 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx TBD - show resultant XML If a server supports branches, then it MUST support this operation. 6.6 Branch Check-Ins Clients can discover the check-ins to a branch using the DAV:checkins. The before and after parameters can be used to qualify the discovery based on creation date. PROPFIND /bn/ci/RYURUS99009 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx TBD - show resultant XML Servers SHOULD support this operation, but are not required to do so. 6.7 Sharing Some version control systems allow resources to be shared across different portions of the namespace. This sharing can take two forms: (a) all references refer to the exact same object and changes are seen everywhere, (b) references to an object are qualified by a specific version and new versions are not automatically seen. This functionality is supported via the proposed referential members and an additional resource property. The property DAV:shareversion and can be set only on referential members. When the property doesn’t exist, the reference is to the default version and all changes are shared. When the property is defined, the reference is to the indicated version only. TBD - give example Servers SHOULD support sharing. 6.8 Resolution Queues There are times when the version store is in a transitory state because of actions that have occurred. The server tracks and maintains lists of issues that need to be resolved as a result of these actions. These lists are referred to as resolution queues. Clients can request the resolution issues and react accordingly. Note that the server only manages the list. That is, the client is responsible for resolving the issue (or deciding not to) and then removing the resolution item. Servers may choose to block operations on a branch or resource until resolutions have been resolved. In this case, an error is returned on any operations against the branch/resource indicating that pending resolution items are present. Servers SHOULD support resolution queues. If a server supports branches, it MUST support resolution queues. 6.8.1 Discovering Resolution Items Conceptually, every object can have associated resolution items. This information is managed on a per-branch basis. Clients request resolution queue information for either a resource or a branch. The reply includes an enumeration of all the resolution items for the requested resources/branch. This is done by issuing a PROPFIND for the property on a branch or a resource. PROPFIND /bn/RYURUS99009 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx HTTP/1.1 Content-Length: xxx Content-Type: text/xml DAV:ZZZZ3493 http:/foo/bar.htm DAV:FDFEE55544 Note that if a server doesn’t support resolution queues. In this case, RESQUEUE method calls will see a NOT IMPLEMENTED result. TBD - define valid reasons: upstream changes, merge conflicts, pinned share updates, ... 6.8.2 Deleting Resolution Items Once a client has resolved an issue, they are responsible for removing it from the queue. This is done by tagging a change or by resolving the resolution item. In the example below, the client updates a document and specifies the resolution item. This item is deleted if the operation is successful. PUT /foo/bar.cpp HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx Resolution-Id: DAV:DDHRH4955 ... In the example below, the client deletes the resolution item. This operation is not guaranteed to succeed as the server may require the action to be resolved. PROPPATCH /bn/DDHRH4955 HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx 6.9 Miscellaneous The following sub-sections detail miscellaneous versioning requirements. 6.9.1 Destroy Many version management systems support the ability to permanently destroy tombstones for an object. The DESTROY method provides this functionality and servers SHOULD support it, but servers are not required to implement it. DESTROY /foo/bar/x.cpp HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx Clients may chose to display deleted but not destroyed objects however they choose. The header keyword Show-Deleted is used to indicate if deleted items should be included in the GET request. By default, this is no. Inclusion of "Show-Deleted: Y" indicates that deleted resources should be included. Using "Show-Deleted: O" indicates that only resources that have been deleted should be returned. If the server does not support the notion of DESTROY, then the operation will return a failure status. 6.9.2 Keyword Expansion A common feature of version control systems is to allow keyword expansion. That is, the resource is automatically annotated with specific information by the server. Servers SHOULD implement this functionality, but are not required to implement this functionality. To support this functionality, several small changes are required. The property Expand-Keywords is available on every resource. This 0/1 resource determines if keywords are to be expanded. There currently exist a number of version control systems that support keyword expansion in a unique fashion. Consequently it is unlikely that a unified definition of the expansions and expansion symbols can be defined. This protocol provides a mechanism for discovering the expansions for a resource that a server supports and the associated expansion symbols. This information is obtained by accessing the read-only property expansionsymbols on any resource. The read-only property expansionsused returns the keyword expansions in use by a specific resource. As well, the property expansiontypes from a branch indicates the file types (based on suffix) for which keyword expansion is enabled. Keyword expansion is on a per-branch basis. However, the branch name "*ALL*" can be specified when setting expansion types to effect the default setting for all branches. This protocol does not specify if keyword expansion occurs on GET or PUT - that is up to each server. Nor is there a requirement for the keywords that must be supported. This is a per-server list. TBD - give example 7 Language Variant Extensions For sites that maintain multi-language variations of resources, the following extensions facilitate this functionality. Note that servers SHOULD support language variants, but are not required to do so. 7.1 Resource Properties Every resource has the read-only property DAV:language-variant. If a server doesn’t support variants, a PROPFIND for this property will return empty or NOT IMPLEMENTED. If the property exists, it returns the language variant associated with the resource. 7.2 Header Extensions The header qualifier Accept-Language allows clients to specify language variants they desire. When this qualifier is present on a GET request, the client specifies the desired variants. Servers take this under advisement, but are not required to return a variant of the requested type. GET /foo.htm HTTP/1.1 Host: www.foobar.com Accept-Language: German, English Content-Type: text/xml Content-Length: xxxx When resources are sent to the server in a PUT request, the client specifies the language variant of the resource using the header tag Content-Language. PUT /foo.htm HTTP/1.1 Host: www.foobar.com Content-Language: German Content-Type: text/xml Content-Length: xxxx ... 7.3 Default Variant For a given Branch (or for all branches), clients can establish the default language variant that is to be used if clients do not request a specific language variant. In the example below, the default variant for all Branches is set to German. PROPPATCH /bn/* HTTP/1.1 Host: www.foobar.com Content-Type: text/xml Content-Length: xxxx German 8 Internationalization Considerations TBD 9 IANA Considerations This protocol defines several new URI schemes: - DAV:, for version-specific references 10 Security Considerations TBD 11 XML Element Definitions Some element definitions are reused from the WebDAV Distributed Authoring Protocol specfication [WebDAV], however, this specification does introduce new DAV: DTD. TBD - define the new DAV: DTD 12 References [RFC2068] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1." RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997. [RFC2119] S. Bradner, "Key Words for use in RFCs to Indicate Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1997. [WebDAV] Y. Y. Goland, E. J. Whitehead, Jr., A. Faizi, S. R. Carter, D. Jensen, "Extensions for Distributed Authoring on the World Wide Web -- WEBDAV". Microsoft, U.C. Irvine, Netscape, Novell. Internet-draft, work-in-progress. [White] E. J. Whitehead, "A Web Versioning Protocol". Work-in-progress. 13 Author’s Address Christopher Kaler Microsoft One Microsoft Way Redmond, WA 98053 Email: ckaler@microsoft.com