CHECKIN/CHECKOUT
Geoffrey M. Clemm (gclemm@tantalum.atria.com)
Tue, 19 Jan 1999 00:19:36 -0500
Date: Tue, 19 Jan 1999 00:19:36 -0500
Message-Id: <9901190519.AA13428@tantalum>
From: "Geoffrey M. Clemm" <gclemm@tantalum.atria.com>
To: ietf-dav-versioning@w3.org
Subject: CHECKIN/CHECKOUT
Even though we missed the Jan 11 deadline, Jim Amsden and I have been
hard at work on the WebDAV versioning model, and hope to have some
documents to send out by the end of January (Jim even flew up to
Mass in last week's ice storm for 2 days to work on it with me,
which definitely deserves a "beyond-the-call-of-duty" award).
Before I get my part of those documents finished up, I wanted to send
out the long-promised "CHECKOUT/CHECKIN" document. This document has
been significantly affected by the results of our modeling efforts, and
so will probably bear only remote resemblance to what folks remember of
the various prior conversations on the subject.
So with that in mind, here's what I've got:
------------------------------------------------------------
CHECKOUT/CHECKIN
Putting a Resource under Version Control
When a resource is put under version control, it becomes unwriteable.
In order to modify a resource, it must first be checked out, then can
be modified one or more times, and then checked back in to indicate
you are done modifying it. If your CHECKOUT fails, it means someone
else is currently modifying the document, so you should only do a GET
with the understanding that the results are only temporarily valid.
Checkout vs. Lock
Note the distinction between a (write) LOCK and CHECKOUT. The LOCK
takes a resource that is writeable by everyone and temporarily makes
it unwriteable by everyone except the lock holder (until it is
UNLOCK'ed). A CHECKOUT takes a resource that is unwriteable by
everyone, and temporarily makes it writeable (until it is CHECKIN'd).
It is reasonable to apply a LOCK to a checked-out resource, but is
not required. In particular, many systems will decide the LOCK
is irrelevant, since a "friendly" client will delay writing until
it can perform a CHECKOUT, and an "unfriendly" client can just wait
until the UNLOCK and then trash the resource contents at will.
Immutable-Revisions
An immutable-revision is a revision whose contents (and immutable
properties) cannot be changed. More precisely, an attempt to retrieve
the contents or immutable properties of an immutable-revision will
always return the same contents or will fail. Therefore a server can
delete the contents or properties of an immutable-revision (resulting
in a failure when an attempt is made to retrieve those contents or
properties), but can never delete the immutable-revision itself.
Mutable-Revisions
A mutable-revision is a revision whose contents and properties can be
changed, although an attempt to change the contents or the "immutable
properties" of a mutable-revision must be preceded by an explicit
"checkout/thaw" operation, and then should be followed by a
"checkin/freeze" operation to return it to a read-only state. This
then requires two flavors of checkout: a checkout that unfreezes an
existing mutable-revision (which I'll call CHECKOUT) and a checkout
that creates a new (unfrozen) mutable-revision that is based on an
existing mutable-revision (which I'll call CHECKOUT-NEW).
Branching
When a versioned resource supports immutable-revisions, it is still
necessary to support "change". In particular, there must be some
resource that you can name, that will periodically take on new values.
For a versioned resource with immutable-revisions, this analogue to a
mutable-revision is called a "branch". Like a mutable-revision, a
branch can be checked-out, changed, and then checked-back in. The tip
of the branch then reflects this change. Also as with mutable
revisions, you sometimes want to check out a new branch that is based
on (the tip of) an existing branch, which requires another flavor of
checkout (i.e. CHECKOUT-NEW).
From a protocol perspective, this provides a way to unify the worlds
of mutable and immtable-revisions. In each world, there is CHECKOUT,
CHECKOUT-NEW, and CHECKIN, where CHECKOUT modifies an existing
modifiable entitity, while CHECKOUT-NEW creates a new modifiable
entity that can be modified in parallel with the original entity.
CHECKIN is used in either case to return the resource to a readonly state.
The alternative is to provide THAW/FREEZE operations that can only be
applied to mutable-revisions, resulting in inoperability between
servers that support mutable-revisions and servers that support
immutable-revisions.
Specifying CHECKOUT/CHECKOUT-NEW Policy
For versioning individual documents, it is sufficient to just let the
user select CHECKOUT or CHECKOUT-NEW, as they see fit. For
versioning sets of related resources that are being modified in
parallel by multiple users over the course of multiple sessions, it is
essential that the server provide a mechanism for the client to store
its versioning policy in a form that can be queried (and updated) by
multiple clients over multiple sessions. This is especially true when
the CHECKOUT choice for a particular resource is dependent on the
current state of the revision graph for that resource. I propose that
the "workspace" resource that stores the version-selection-rules is
the appropriate place to store this information, since the modification
and creation of new revisions must be synchronized with the
version-selection-rules, or else newly created revisions might
disappear from view as soon as they are checked in.
Bottom line: A CHECKOUT, CHECKOUT-NEW, and CHECKIN command, with no
special CHECKOUT/IN headers (which should make Larry happy :-).
Note for Dave: The CHECKIN-NEW would be used to produce the "anonymous
new change-set" you wanted.
Note for Brad: A workspace property would be used to achieve the
-force_branch_on_new_version functionality that you wanted.
Note for All: This doesn't discuss UNCHECKOUT.
Cheers,
Geoff