Goals for Web Versioning

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 view the list Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html.

Distribution of this document is unlimited. Please send comments to the Distributed Authoring and Versioning (WebDAV) working group at ietf-dav-versioning@w3.org, which may be joined by sending a message with subject "subscribe" to ietf-dav-versioning-request@w3.org. The main WebDAV mailing list at w3c-dist-auth@w3.org may also be used for comments. It may be joined by sending a message with subject "subscribe" to w3c-dist-auth-request@w3c.org.

Discussions of the WebDAV versioning working group are archived at http://lists.w3.org/Archives/Public/ietf-dav-versioning/. Discussions of the WebDAV working group are archived at http://www.w3.org/pub/WWW/Archives/Public/w3c-dist-auth.

Abstract

Versioning and configuration managerment are important features for controlling the evolution of remotely authored Web content. Parallel development leverages versioning capability to allow multiple authors to simultaneously author Web content. This document supersedes the versioning-related goals of [WEBDAV-GOALS].

Contents

Introduction

Versioning, parallel development, and configuration management are important features for remote authoring of Web content.  Version management is concerned with tracking and accessing the history of important states of a single Web resource, such as a standalone Web page.  Parallel development provides additional resource availability in multi-user, distributed environments and lets authors make changes on the same resource at the same time, and merge those changes at some later date. Configuration management addresses the problems of tracking and accessing multiple interrelated resources over time as sets of resources, not simply individual resources.  Traditionally, artifacts of software development, including code, design, test cases, requirements, help files, and more have been a focus of configuration management.  Web sites, comprised of multiple inter-linked resources (HTML, graphics, sound, CGI, and others), are another class of complex information artifacts that benefit from the application of configuration management.

The WebDAV working group originally focused exclusively on defining version management capabilities for remote authoring applications, and group consensus on these features is reflected in [WEBDAV-GOALS]. However, as the WebDAV working group has constructed protocols for versioning functionality, it has become clear that while versioning functionality alone is useful for a range of content authoring scenarios involving one, or a small set of resources, versioning alone is insufficient for managing larger sets of content. Protocol support for parallel development and simple remote configuration management of Web resources provides functionality for managing larger sets of interrelated content developed by multiple users at different locations.

This document describes functional goals for versioning, parallel development, and configuration management of Web resources which replace the existing functional goals for versioning capability described in [WEBDAV-GOALS], section 5.9.

Definitions

1. A basic resource is a resource that is not a collection or reference, i.e., an HTTP/1.1 resource.
2. A versioned resource is an abstraction for a resource which is subject to version control, a resource having a set of revisions, relationships between those revisions, revision names, and named branches that track the evolution of the resource. 
3. A revision is a particular version of a versioned resource. An immutable revision is a revision that once created, can never be changed without creating a new revision. A mutable revision is a revision that can change at any time without creating a new version.
4. A working resource is an editable resource derived from a revision of a versioned resource by checking out the revision. A working resource becomes a new revision on checkin.
5. A root revision (initial revision) is the first revision of a versioned resource and has no predecessors within the versioned resource.
6. A revision name is a unique name which can be used to refer to a revision of a versioned resource. There are two types of revision names, revision identifiers or labels as described below.
7. A revision identifier (or revision ID) is a revision name which uniquely and permanently identifies a revision of a versioned resource. Revision identifiers are assigned by the server when the revision is created and and cannot be changed later to refer to a different revision.
8. A label is a revision name which uniquely, but not necessarily permanently identifies a revision of a versioned resource. A label may be assigned to a revision, and may be changed to refer to a different revision at some later time. 
9. A predecessor of a revision is an immutable revision from which this revision is derived. A successor of a revision is a revision derived from this revision. A revision may have multiple predecessors and successors. The is-derived-from relationships between revisions of a versioned resource form a directed acyclic graph (DAG).
10. An ancestor of a mutable revision is a revision from which this revision was derived. A descendent of a revision is a revision that was derived from this revision. A mutable revision may have multiple ancestors and descendents. The was-derived-from relationships between revisions of a versioned resource form a directed acyclic graph (DAG).
11. A revision history is a concrete representation of the elements of a versioned resource: all predecessor and successor relationships, revision names.
12. A line-of-descent is a sequence of revisions connected by successor/predecessor relationships from the initial or root revision to a specific revision.
13. An activity is a named set of revisions that correspond to some unit of work. Activities are created by authors and are used to organize related changes to resources, and to provide a basis for merging concurrent changes to the same resource. An activity can contain revisions of multiple versioned resources, and/or multiple revisions of the same versioned resource along a single line-of-descent.
14. A conflict report lists all revisions that must be merged when one activity is merged into another. If the merge source activity specifies a resource that is a predecessor or successor of the revision selected by the current workspace, then there is no conflict. The merged workspace will pick the revision already in the workspace if the merge source specifies a predecessor, otherwise it will pick the successor specified by the merge source. A conflict results when the merge source activity picks a revision on a different line-of-descent than that selected by workspace.
15. A configuration is a named set of related resources where each member refers to a specific revision of a versioned resource. Configurations are similar to activities,   but play a different role. An activity is associated with work in progress and encapsulates a set of related changes to multiple versioned resources. Creating separate activities allows developers to work in parallel on the same resources, and to reconcile conflicts through merging activities. Configurations represent a persistent selection of revisions of versioned resources for organization and distribution. Configurations can   be versioned resources, activities cannot.
16. Configuration management (CM) is the ability to access and manipulate configurations as first-order entities, rather than by working on each versioned resource independently.
17. A workspace is a resource that is used to determine what revision of a versioned resource should be accessed. When a user agent accesses a resource, a workspace may be specified to determine the specific revision that is the target of the request. A workspace contains a version selection rule that is applied when the workspace is used in conjunction with the URI for a versioned resource to select a specific revision.
18. A version selection rule specifies what revision of a versioned resource should be selected. WebDAV defines selection rules that allow a revision to be selected based on revision name, branch name, or configuration name. Servers may support additional selection rules.

Example

This section provides an example usage scenario that provides a context for explaining the definitions above, and for exploring and validating the goals given in the rest of this document. The example consists of a fictious company, Acme Web Solutions, that is developing a typical Web e-business application. To provide for the broadest coverage, the scenarios start with a non-existant resource typical of web applications, and follow its life-cycle through development and multiple deployments. Other resources would likely have similar life-cycles.

Acme Web Solutions (AWS) has developed a web-grocery store called WGS. The application consists of a number of HTML pages, some Java applets, some Java Server Pages (JSP) and a number of Java servlets that access a DB2 database.

AWS has decided to develop a new generation of its flagship WGS product to include maintenance of customer profile information, and active (push) marketing of product specials to interested customers using Channel Definition Format (CDF). The new product will be called Active Grocery Store or AGS. Customers who are interested in receiving information on specials will indicate that interest by subscribing to various CDF channels targeting pre-defined, or user-specified product groupings. Since AGS represents significant new revenue potential for grocery stores, AWS has decided to sell it as a separate product from WGS, and at a relatively high price. WGS will still be available without AGS as a lower-cost, entry level solution for smaller stores, or stores just getting into e-business solutions.

AGS is a typical Web application development project that will require changes to existing resources in AWS as well as adding new resources. These new resources will also be HTML pages, applets, JSPs, servlets, etc. WGS is an active project sold to current customers with a maintenance contract. It has on-going updates that are unrelated to the new AGS system, but may need to be included in the AGS system. These include bug fixes or minor new functional improvements. Since AGS is based on WGS, but both can evolve and be sold separately, it is necessary to maintain versions of resources used by both. This will require AWS developers to specify a configuration of versioned resources corresponding to each product. As the products evolve over time, these configurations will be versioned resources themselves, each representing a new release of their associated product, WGS or AGS.

The AWS development organization consists of a large number of developers across a variety of disciplines including webmasters, Java developers, relational database developers, HTML page editors, graphics artists, etc. All of these developers contribute to the development of the WGS and AGS products, often working in parallel on the same resource for different purposes. For example, a WGS developer may be editing an HTML page to fix a usability problem while an AGS developer is working on the same page to add the new AGS functions. This will require coordination of their activities to provide maximum availability of these shared resources while at the same time ensuring the integrity of the updates. AWS has decided to allow parallel development and resolve multiple concurrent updates through branching and merging of the resource version graph. This adds complexity to the development project as well as some risk due to inaccurate merges, but AWS has decided it cannot be competitive in the Web world if all development must be serialized on shared resources as this would significantly slow product development.

The following scenarios trace the life-cycle of a typical Web resource from conception to product deployment and maintenance. Each scenario exposes some aspect of WebDAV and its use of the versioning, parallel development, and configuration management definitions and goals specified in this document. In the scenarios below, it is assumed that all developers have access to a Web WorkBench (WB) application that provides client access to a WebDAV server called DAVServer. It is further assumed that both the client and server provide level 2 WebDAV services plus advanced collections, versioning, parallel development, and configuration management.

Resource Creation

The AGS project team held a design meeting to determine the work products required to support the AGS project, its integration with the WGS application, and to assign these work products to developers. Various analysis and design techniques can be used to discover the required work products, but this is beyond the scope of WebDAV. At the end of the meeting, webmaster Joe was assigned to develop the new welcome page, index.html, for the AGS project. This page will be the initial page used to navigate the AGS application, and is the first page seen by users. It is a new page that will not replace the WGS welcome page, but will contain a reference to it.

Joe uses WB to create create a new collection, http://aws/ags/, and the new index.html page in the collection http://aws/ags/index.html. Nether the parent collection, nor index.html are versioned resources at this point. A WebDAV MKCOL is used to create the collection, and a PUT is used to create the initial, empty resource.

Resource Editing

Joe uses WB to GET the resource and edit it with his favorite HTML editor. Each save by the HTML editor does a PUT to the DAVServer, overwriting its current contents. No new versions are created. Joe may also use WB to get and set properties of index.html using PROPFIND and PROPPATCH. Joe does not need to lock index.html because he is the only developer working on it at this time. He could however lock the resource to ensure no one else could make any changes he is not aware of.

Creating a Versioned Resource

At some point, Joe decides preliminary editing on index.html is complete, and he needs to make a stable version available to other developers who need it for integration testing, etc. Joe however wants to ensure that no other developers make changes to to index.html that he cannot back out as he is the webmaster responsible for the resource. So Joe uses the WB to check in index.html which causes DAVServer to create a versioned resource, and make the initial or root version Joe's index.html. At this point, Joe's index.html is immutable, it cannot be changed by anyone, including Joe, and remains in the repository until the versioned resource is deleted.

Labeling a Version

When DAVServer created the versioned resource corresponding to index.html, it gave the initial version a revision id, "102847565".  This revision name is automatically assigned by the server, and cannot be changed or assigned to any other version. This revision name acts as the unique identifier for this version of versioned resource index.html. The AGS development team has decided that the initial version of all resources will be identified by a revision label "initial" so that they stand out and can be easily accessed without remembering some opaque revision id. Joe uses WB to set the label on the initial version to "initail" in order to identify the version with this more meaningful name.

Accessing Versioned Resources

Fred wants to access Joe's initial version of index.html. So he uses URL http://aws/ags/index.html to get the contents of the resource and notices he does get the right version, because it was selected by the default workspace. That is, when Fred accessed URL http://aws/ags/index.html, he did so without specifying a workspace. So the default workspace was used, and the default workspace always uses "latest" as its version selection rule. But Fred wants to be more cautions. He wants to be sure that he continues to get version labeled "initial", even if the latest version changes as the result of new changes Joe may check in. So Fred creates a workspace called "initialws", and sets the version selection rule to be the revision labeled "initial". Then Fred always access index.html with its URL and the initialws workspace to be sure he gets the specific version he needs.

Creating a New Revision

A week later, a number of developers have noticed that index.html is missing both important references to their pages as well as hot images for navigation. They send email to Joe specifying their new requirements. Joe now wants to make changes to index.html and create a new version. He wants to retain the old revision, just in case the requirements he was given were incorrect and need to be backed out, and to allow developers using the old revision to continue their work. To do this, Joe uses the WB to check out index.html and create a new working resource. Joe can now access the working resource because working resources are always visible from the workspace in which they were checked out.

As before, Joe uses the WB and HTML editor to GET the working resource and PUT updates. Each PUT replaces the contents of the working resource with changes made by the HTML editor, no new revision is created. When Joe is finished making edits to support the new requirements, he checks the working resource back in, making a new revision.

Editing a Mutable Revision

John was assigned to write a high level marketing document, ags.html, that provided an overall description of the AGS application. Since most changes to this document have no effect on the rest of AGS, John decides to allow revisions of ags.html to be editable. This is so simple spelling and grammar errors can be fixed without requiring the creation of a new revision. John still wants to create revisions whenever some significant new feature is added to AGS so the old descriptions are available to customers who don't upgrade.

John creates resource ags.html, edits it a number of times, and then checks it in to create a versioned resource. But in this case, John checks in ags.html as a mutable revision so he can fix spelling mistakes, etc. by simply doing a PUT to the mutable revision, just like a non-versioned resource or working revision.

Later on, a new feature is added and John checks out ags.html to create a new revision, makes his edits and checks it back in, again as a mutable revision. In this case, the descendent is related to the ancestor by a was-derived-from relationship to indicate that ancestor revision might change.

Six months later, there have been a number of complaints about ags.html presenting misleading product information that has resulted in unhappy customers. There's even talk of law suits (read money-making opportunities). So John hurriedly updates ags.html and checks in the new version as immutable so that in case there is a suit, he can prove that customers had access to his updated version. Now any changes can be made by creating new immutable revisions without ever worrying about loosing old version.

A year later, things have cooled down, and John decides its OK to allow mutable revisions again. On his last change he checked ags.html in as a mutable revision allowing subsequent changes to be done without creating new versions. At the same time, the revision history of the immutable revisions is preserved just in case that pesky customer re-appears.

Parallel Development With Activities

Two weeks later, there is a major redesign of AGS that results in a lot of changes to index.html. Again, Joe checks out the resource creating a new working resource. But it is taking Joe a long time to finish all the edits, and in the meantime, graphics artist Jane wants to update index.html with references to the new images that resulted from the AGS redesign. Jane attempts to check out index.html, but WB informs her that Joe already has it checked out and refuses the request. She checks with Joe, and since they are both working on different aspects of index.html, Joe feels it would be fine for Jane to do her work in parallel with his, and then he will merge her changes with his to finish the required updates. Jane creates a new activity called "images_updates", uses it to set the activity of her workspace, and again attempts the checkout. This time the checkout succeeds, and a new working resource is created for index.html in the images_updates activity. Now any changes that Jane makes to images.html are completely independent of changes Joe makes to the same resource, but in a different activity. Note that Joe did not create an activity when he checked out index.html. Instead, the default activity "mainline" was used. Jane couldn't checkout index.html without specifying a different activity because a resource can only be checked out once in a given activity.

After making her edits, she checks index.html back in, which creates a new revision in the images_updates activity. There is still no need for Joe or Jane to lock index.html as they are working on different working resources in different workspaces. Again, either of them may lock their working resource to ensure no one else can change it.

Merging Activities

Project management practice dictates that at various times during the development project, usually every few days or at specific project milestones, the updates from any parallel activities should be merged in order to integrate the changes and produce instances of the products suitable for testing. This avoids the risk of revisions of shared resources diverging wildly, and thereby decreases the likelihood of difficult or inaccurate merges. It also encourages communication within the development organization and avoids "big-bang" integration points late in the development cycle. This enhances the stability of the products and helps ensure a deterministic, controllable development process. It also allows early product testing and better feedback to developers.

Joe has finally finished his changes to image.html, and is ready to incorporate the changes from Janes images_update activity to get the new images. Before doing so, Joe checks his updates into revision "r0.2" so if he does something wrong when doing the merge, he can recover and try again. Now Joe specifies in his workspace that he wishes to merge the "image_updates" activity into his workspace. He then can obtain a conflict report from his workspace which indicates that the resource index.html requires a merge. He then issues a merge request for index.html. This checks out the resource in the mainline activity (the activity in Joe's workspace), and registers a merge from the latest revision in the image_updates activity to the working resource. This working resource now has two predecessors, r0.2 and the image_updates revision. Joe then uses the differencing capability in his HTML editor to find the differences between his revision and Janes, and to apply Jane's changes as appropriate.

The HTML editor Joe uses is WebDAV versioning aware, and does a 3-way merge by accesses the closest common ancestor in the revision history in order to help with the merge process. Joe notices that most of Janes changes do not conflict with his as they are in different places in the resource, but there are a number of places where he added new functions that do not have images as Jane didn't know they were there. He notes these and either fixes them himself, or sends email to Jane so she can fix them in another version. Once the changes are complete, Joe checks in the merged version. Jane is free to continue making updates in her image_updates activity, and these changes can be merged in again later.

There is still no need for Joe or Jane to lock index.html as they are both working on different working resources. Again, either of them may lock their working resource to ensure no one else can change it.

Creating a Configuration

At some point, enough of the work products of the AGS application are sufficiently complete and stable that AWS wants to distribute an alpha release. To do this, Joe uses WB to create a configuration named "alphaRelease" that will contain a consistent set of compatible work products. This configuration will contain all revisions currently selected by Joe's workspace. If any working resources exist in Joe's workspace, the request to create a configuration fails, with an error message indicating that the failure is due to the presence of checked-out resources in Joe's workspace.

When Joe is happy with the state of the his workspace (including the mainline activity), he can create a "configuration" (see below). When Jane is ready to see this new state, she would modify the version selection rules of her workspace to select this new configuration. Any conflicts between this new configuration and her current activity requiring merges would be noted in the "conflicts" report of her workspace, which Jane could then resolve with the "merge" operation.

Getting the Revision History of a Versioned Resource

Changing a Revision

Accessing Resources by Non-versioning Aware Clients

Updating Resources by Non-versioning Aware Clients

Goals

This section defines the goals addressed by the protocol to support versioning, parallel development, and configuration management. Each goal is followed by a short description of its rationale to aid in understanding the goal, and to provide motivation for why it was included.

1. Versioning aware and non-versioning aware clients must be able to interoperate. Non-versioning aware clients will not be able to perform all versioning operations, but will, at a minimum, be capable of authoring resources under version control and be capable of creating new revisions. Non-versioning aware clients are HTTP/1.1 and versioning unaware WebDAV clients.
   
   Versioning and configuration management adds new capabilities to WebDAV servers. These servers should still be responsive to non-versioning aware clients in such a way that these clients retain their capabilities in a manner that is consistent with the versioning rules. For example, non-versioning aware clients should be able to GET the contents of a versioned resource without specifying a version and get some well-defined default revision. A non-versioning aware client should be able to PUT to a versioned resource and have a new revision be automatically created. A subsequent GET on the same versioned resource by this client should return the new revision.
   
   
2. It must be possible to version resources of any media or content type.
   
   Versioning capabilities must not depend on the media type of the resource or versioning would have limited applicability, and client applications would become more complex.
   
   
3. Every revision of a versioned resource must itself be a resource, with its own URI.
   
   See section 5.9.2.2 of [WEBDAV-GOALS].  This goal has two motivations. First, to permit revisions to be referred to, so that (for example) a document comparing two revisions can include a link to each. Second, revisions can be treated as resources for the purposes of DAV methods such as PROPFIND.
   
   
4. It should be possible for a client to specify meaningful labels to apply to individual revisions, and to change a label to refer to a different revision.
   
   Although unique revision IDs are assigned by the server, human-meaningful aliases are often useful.  For example, a label called "CustomerX" could be assigned to the latest revision of a document which has been delivered to customer X. When X calls to inquire about the document, the author(s) can simply refer to the label, rather than maintaining a separate database of which revisions have been shipped to which customers.
   
   
5. It must be possible to use the same label for different versioned resources.
   
   This allows authors to indicate that revisions of different resources are somehow related or consistent at some point in time. Configurations formalize this relationship.
   
   
6. The labels and revision IDs within a revision history are names in a common namespace, in which each name must be unique.  The server may partition this namespace syntactically, in order to distinguish labels from IDs. The server enforces uniqueness for these labels.
   
   This means the same label cannot apply to multiple revisions, the same revision ID cannot apply to multiple revisions, and no label can also be a revision ID or vice versa.  This is required so that a label, when applied to a versioned resource, refers to one and only one revision, and all revision names for a versioned resource are unique. To enforce uniqueness, a server will have to reject labels which it might eventually use as revision IDs. The simplest way to do this is to partition the namespace.
   
   
7. Given a URI to a versioned resource, and a revision name, it must be possible for a client to obtain a URI which refers to that revision. 
   
   This allows specific revisions of a resource to be accessed given the URI of the versioned resource and a revision name.
   
   
8. Relative URLs appearing in versioned HTML documents which are being edited and/or browsed by a versioning-aware client should work correctly.
   
   Web resources and client applications often refer to other resources with relative URLs, an incompletely specified URL that is completed by prepending some known context that would not contain a revision name. When used with versioned resources, these relative URLs may be relative to a versioned resource or a particular revision. In this case, the context must include sufficient information for the relative URL to be resolved to a specific revision.
   
   
9. If the DAV server supports searching, it should be possible to narrow the scope of a search to the revisions of a particular versioned resource.
   
   It is often the case that one needs to find, for example, the first revision at which a particular phrase was introduced, or all the revisions authored by a particular person.  Given search capabilities for collections, it would be far more sensible to leverage those capabilities than to define a separate search protocol for revision histories.  For example, if the server supports [DASL], then the revision histories could be searched via DASL operations.
   
   
10. If the DAV server supports searching, revision IDs and label names should be searchable.
    
    This would allow client applications to search for resources that have a particular revision name.
    
    
11. The CM protocol must be an optional extension to the base versioning protocol.
    
    It is expected that servers will want to support versioning without supporting configuration management. This goal provides the required flexibility.
    
    
12. Revisions are either mutable or immutable. Once an immutable revision has been checked in, its contents and immutable properties can never be changed. A mutable revision can be updated at any time without creating a new revision.
    
    The concept of mutable revisions is included to support typical document management systems that want to track version histories while allowing more flexible, less formal versioning semantics.
    
    
13. Each immutable revision may have properties whose values may be changed without creating a new revision.  The list of these properties must be discoverable.
    
    It is expected that certain live properties whose values are calculated by the server may depend on information that is not captured in the persistent state of an immutable revision. The values of these properties may change from time to time without requiring a new revision of the versioned resource. There may also be some DAV properties used to support versioning and configuration management that may change without requiring a new revision.
    
    
14. Revisions can be deleted. Generally this is a high-privilege operation.
    
    This goal is included to support generally necessary maintenance operations on versioning repositories. It is sometimes the case that predecessors of a revision beyond some point are no longer required and can be removed from the repository to reclaim space. It may also be the case that a versioned resource is no longer used and can be safely deleted. This goal does not intend to express any policy for when or under what circumstances revisions can be deleted. It only provides a mechanism to support particular client or server policies.
    
    
15. Once a revision has been deleted, its ID cannot be reused within the same versioned resource.
    
    In many cases, it is necessary to be able to guarantee (as far as possible) that one can retrieve the exact state of a resource at a particular point in history, and/or all the states which the resource has ever taken on.  For example, if a company is sued for violating a warranty which the plaintiff read on the company's Web site, it may be useful to be able to prove that the warranty never contained the provision which the plaintiff says it did (conversely, it may be useful for the plaintiff to be able to prove that it did).  A revision history where all revisions were immutable would provide this sort of ability.
    
    Of course, DAV cannot preclude the possibility of an out-of-band method to change or delete a revision; an implementation may provide an administrative interface to do it.  But such access would at least be limited to trusted administrators.
    
    
16. A configuration can only contain immutable revisions.
    
    This requirement is included in order to retain the usual semantics of configurations, and to ensure that a configuration can always be recreated.The implication is that un-versioned resources, working revisions, and mutable revisions cannot be members of a configuration.
    
    
17.  It must be possible to query a revision history to learn the predecessors and successors of a particular revision, branch names, the root and default revisions, etc.
    
    If a client wishes to present a user interface for browsing the revisions of a particular versioned resource, it must be able to read the relationships represented within the version history.
    
    
18. It should be possible to obtain the entire revision history of a versioned resource in one operation.
    
    A client wishing to display a map of the revision history should not have to make queries on each individual revision within the revision history; it should be able to obtain all the information at once, for efficiency's sake.
    
    
19. The protocol must support activities as an optional capability.
    
    Activities support controlled parallel development on the same resource, but results in the need to merge multiple changes at some later time. This introduces work and the potential for errors that some servers may want to avoid by requiring updates to be serialized.
    
    
20. The protocol must support the following operations:
    1. Creating revisions:
    • Obtain the URI of a revision given the URL for the versioned resource and either a label, revision ID, branch name, or configuration name.
    • Check out a revision in an activity and create a working resource.
    • Check in a working resource and create a mutable or immutable revision.
    • Cancel a checkout (delete a working resource).
    • Describe a revision with human-readable comments.
    2. Labels:
    • Apply a label to a particular revision.
    • Change the revision to which a label refers.
    3. Activities:
    • Create and name an activity.
    • Rename a activity.
    • Merge an activity into a workspace.
    • Generate and maintain the conflict report for a merge
    4. Configurations:
    • Create a configuration.
    • Add/remove revision from a configuration.
    • Access a revision given a configuration name that contains it.
    • Delete a configuration.
    • Use a configuration in a version selection rule for a workspace

    Some of these operations come from [WEBDAV-GOALS], section 5.9.1.2.  Not all of the operations in that section are replicated here; some of them (e.g., locking) fall out naturally from the fact that a revision is a resource.
    
    The protocol must find some balance between allowing versioning servers to adopt whatever policies they wish with regard to these operations and enforcing enough uniformity to keep client implementations simple and interoperable.
    

21. For each operation that the protocol defines, the protocol must define that operation's interaction with all existing [WebDAV] methods on all existing WebDAV resources.
    
    This goal applies to all HTTP extensions, not just versioning. However, versioning, parallel development, and configuration management are sufficiently complex and have a broad enough effect on other methods to call out this goal specifically.
    
    
22. The protocol should clearly identify the policies that it dictates and the policies that are left up to versioning system implementors or administrators.
    
    Many writers, have discussed the notion of versioning styles (referred to here as versioning policies, to reflect the nature of client/server interaction) as one way to think about the different policies that versioning systems implement. Versioning policies include decisions on the shape of version histories (linear or branched), the granularity of change tracking, locking requirements made by a server, etc.
    
    
23. A client must be able to determine whether a resource is a versioned resource, or whether a resource is itself revision of a versioned resource.
    
    A resource may be a simple, non-versioned resource, it may be a mutable or immutable versioned resource, or it may be a a particular revision of a versioned resource. A client needs to be able to tell which sort of resource it is accessing.
    
    
24. There must be a way to refer to a server-defined default revision of a versioned resource.
    
    The server should return a default revision of a resource for requests that ask for the default revision, as well as for requests where no specific version information is provided. This is one of the simplest ways to guarantee non-versioning client compatibility. This does not rule out the possibility of a server returning an error when no sensible default exists.
    
    It may also be desirable to be able to refer to other special revision of a versioned resource. For example, there may be a current revision for editing that is different from the default revision. For a graph with several branches, it may be useful to be able to request the tip revision of any branch.
    
    The association of a workspace with a particular user agent for the purposes of applying version selection rules is the responsibility of the client application. The server does not retain this association.
    
    
25. It must be possible, given a reference to a revision of a versioned resource, to find out which versioned resource that revision belongs to.
    
    This makes it possible to understand the versioning context of the revision. It makes it possible to retrieve a revision history for the versioned resource to which it belongs, and to browse the revision history. It also supports some comparison operations: It makes it possible to determine whether two references designate revisions of the same versioned resource.

Rationale

Versioning in the context of the world-wide web offers a variety of benefits:

It provides infrastructure for efficient and controlled management of large evolving web sites. Modern configuration management systems are built on some form of repository that can track the revision history of individual resources, and provide the higher-level tools to manage those saved versions. Basic versioning capabilities are required to support such systems.

It allows parallel development and update of single resources. Since versioning systems register change by creating new objects, they enable simultaneous write access by allowing the creation of variant versions. Many also provide merge support to ease the reverse operation.

It provides a framework for coordinating changes to resources. While specifics vary, most systems provide some method of controlling or tracking access to enable collaborative resource development.

It allows browsing through past and alternative versions of a resource. Frequently the modification and authorship history of a resource is critical information in itself.

It provides stable names that can support externally stored links for annotation and link-server support. Both annotation and link servers frequently need to store stable references to portions of resources that are not under their direct control. By providing stable states of resources, version control systems allow not only stable pointers into those resources, but also well-defined methods to determine the relationships of those states of a resource.

It allows explicit semantic representation of single resources with multiple states. A versioning system directly represents the fact that a resource has an explicit history, and a persistent identity across the various states it has had during the course of that history.

Non-goals

These non-goals enumerate functionality which the working group has explicitly agreed to exclude from this document; they are documented here for explanatory purposes. 

1. Revisions in multiple revision histories (see [WEBDAV-GOALS], sections 5.9.1.3 and 5.9.2.5).  This capability was felt to be too rarely useful.
2. Federated revision histories (that is, revision histories which are not stored on a single server).  This capability would introduce great difficulties.  A server implementor who needs it can use out-of-band server-to-server communication; but this communication is arguably out of the scope of WebDAV, which is a client-to-server protocol.
3. Client-proposed version identifiers (see [WEBDAV-GOALS], section 5.9.2.8).  Labels do the job better.

Security Considerations

To be written.  It is likely that implementing features to meet the goals described here will present few or no new security risks beyond those of base DAV.  One possible exception is that it may become more difficult to hide the contents of a resource when there may exist other versions with different access control lists.

References

[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", Internet-Draft draft-ietf-webdav-protocol-10. Nov., 1998
[WEBDAV-GOALS] J. Slein, F. Vitali, J. Whitehead, D. Durand, "Requirements for a Distributed Authoring and Versioning Protocol for the World Wide Web", RFC-2291.  February 1998.
[WEBDAV-ACP] J. Slein, J. Davis, A. Babich, J. Whitehead, "WebDAV Advanced Collections Protocol", Internet-Draft draft-ietf-webdav-collection-protocol-02.txt.  Nov., 1998.
[DASL] S. Reddy, D. Jensen, S. Reddy, R. Henderson, J. Davis, A. Babich, "DAV Searching & Locating", Internet-Draft draft-reddy-dasl-protocol-04.txt.  Nov., 1998.
[CVS] http://www.cyclic.com/cyclic-pages/books.html
[BONSAI] Mozilla.org, http://www.mozilla.org/bonsai.html