Core versioning scenario and mutability

Here's the longer email I promised on mutability and human-readable
version URLs.

Scenario
--------

This scenario involves only document versioning.  It does not involve
code versioning.

A specification or proposal is being developed where there is a primary
author using a document application like Word, and a group of people who
use web browsers to view the document and comment on it to the primary
author.  E.g. "draft-ietf-deltav-versioning.htm".  (I'll ignore the IETF
submission and naming rules for simplicity.)

In this scenario, Geoff makes changes to the document on the server.
It's easiest for him to do it on the server, because then he doesn't
have to worry about keeping local versions synchronized with server
versions.  When Geoff has made a number of changes & decides that the
working group should review the version, he presses a button in his word
processor to effectively "create new version".  He obtains a URL which
he can send in email to the working group, and the members of the
working group use their web browsers to click on the URL & read the
document.

On the deltav web site, Geoff places a link to
"draft-ietf-deltav-versioning.htm".  The server automatically treats a
request for this URL as a request for the latest _checked-in_ version,
and returns that.  Therefore, Geoff doesn't have to update his web page
every time he checks in a new version.

Sometimes, Geoff sends out the URL to a version (e.g. v10) and then
notices a minor mistake.  Maybe he has to change Jim Whitehead's
affiliation from UC Irvine to UCSC.  But he's already sent out the URL
to v10!  Happily, his WebDAV document versioning server supports
mutability.  Geoff makes the change and doesn't have to send out a new
email with a new version URL.

The power is in the author's hands in this scenarios.  Geoff controls
the versioning, and he's the person best suited to; he knows when a new
version is appropriate, and neither the client software nor the server
software can make that judgement.  The server is really only a servant,
not putting unnecessary rules in the way of Geoff doing what he wants
to:  creating versions when and as he wants, changing versions when and
as he wants.  If Geoff does this poorly, it's his fault, not the
software's, but in the document versioning scenario, it's not the end of
the world.  There is a principle here of the software not putting
unnecessary rules in the way of the user.  I'd suggest it's even worse
for a protocol to put unnecessary rules in the way of the user, because
the protocol standard enforces those rules on every implementation.

Assumptions
-----------

I am making the following assumptions:
 - It is not necessary -- and very often not desirable -- to track every
minor change to a document in a new version.
 - Some document applications (e.g. Word) have in-place "AutoSave"
features.  Even without AutoSave, users sometimes hit "save" as they go
along.  In Word, when editing a doc on a webDAV server, this saves to
the server (and Word is NOT going to change that!).
 - It is sometimes interesting to view past versions of a document.
 - Labels are too complicated to be used by simple document applications
(e.g. Word)
 - Labelled versions aren't interoperably expressible in URLs
 - Some of the clients viewing these documents will be simple web
browsers.


Requirements
------------

Mutability

Because of auto-save and user hitting "save" during editing, the server
MUST NOT create a new version every time the client does a
PUT/PROPPATCH.  The server must only create a new version when the
author specifically requests it.  This could be whenever a CHECKOUT is
performed.  A client application can then have a single button for
"create a new version" and when that button is pressed it does a
CHECKOUT and a CHECKIN sequentially.  Every other change to the document
is done via PUT and modifies only the latest version.

Human-readable version URLs

Human-readable version URLs are desirable.  The advantage is that users
can visually see whether they are about to navigate to v9, v10, v11, or
the base document (latest version).  If the version URLs are too
complicated or long (e.g. if they contain GUIDs), users will not bother
to visually parse the URL to see what version they are looking at.  This
is not disastrous, but it is a pain: Geoff is likely to get comments on
v9 that have been fixed in v10, because the user didn't realize what
version they were looking at.


Conclusion
----------

Core versioning is nearly capable of fulfilling this scenario.  What is
desirable/required:
 - Version URLs may be re-used
 - Mutability can be supported by a core server.  This may have to be
codified to improve interoperability; I can make some suggestions along
those lines:
	- CHECKOUT of a resource-URL creates a new version
	- CHECKIN resets the "target" property of the base resource to the
checked-in version
	- PUT/PROPPATCH of a resource-URL modifies the latest version (the one
checked out, if there is one)
	- PUT/PROPPATCH of a version-URL mutates the version in-place
	- PUT/PROPPATCH never create a new version

If this is sufficiently different from code-versioning scenarios to
reduce interoperability, and it may be, I can suggest a number of
possible remedies:
 - The versioning draft can split into two, one for code-versioning and
one for document-versioning.
 - Some "package" can be specified in the response to OPTIONS: if the
server responds with "mutable-versioning" the client understands it
follows the model outlined here.  However, if the server responds with
"immutable-versioning", the client understands that every CHECKOUT, PUT,
PROPPATCH (etc) makes a new version.
 - Rather than call this package "core" -- which makes it seem like all
servers, including code-versioning servers, have to support this
package -- call this package "mutability-support" or whatever.  I
completely understand that code-versioning servers do not want to follow
the mutability model.
 - It might be possible to have "major versions", for which version-URLs
are human-readable, and "minor versions", for which version-URLs are
guaranteed not to be reused.  I feel this would add too much complexity
(we'd have to extend CHECKOUT to specify major-version or
minor-version), but it would be better than nothing.

Lisa

Received on Friday, 5 January 2001 13:39:30 UTC