Re: Core versioning scenario and mutability

Preamble: After reading through Lisa's scenario, I believe that
there's a much simpler answer to what Lisa needs than my "use labels"
suggestion.  In particular, let's suppose we just added a
"delete-checked-out" option to the CHECKIN request.

And then, for down-level client compatibility, let's also add a
"delete-checked-out" value for "auto-version" (so you can tell
a server to delete the previous version of that version-controlled
resource by default, whenever a downlevel client creates a new version).

So with that context, let's get back to Lisa's scenario.
Actually, it's Lisa's "geoff scenario" (:-), so I guess I
should say, let's get back to "our scenario".

   From: "Lisa Dusseault" <lisa@xythos.com>

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

And the protocol is designed to work for document versioning,
so this is certainly an important scenario.

   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.  

Well, I would never work on an important document like the protocol
without keeping it under version control (:-), so actually, I create
many versions locally (checking them all in to a version control
system), and only when I reach a "publishable" version, do I update
the draft-id in the document and publish it to the web site.  When
I "publish" it, I actually use the draft-id in the URL, rather
than the version-id, because the draft-id is a "friendlier" name.

But it *sure* would be nice if the resource I published it to
would remember that it actually is version "/main/157" (perhaps
in its DAV:precursor property :-).

Every so often, I actually go back to look at one of the "unpublished"
versions, because I remember making some change that I decided to
back it out before publishing, but I didn't want that change lost.
Sometimes I even cut/paste something from one of those unpublished
versions into the current version.

   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.

Yes, I create a new resource whose human meaningful URL contains
the new draft-id.

   On the deltav web site, Geoff places a link to
   "draft-ietf-deltav-versioning.htm".

Actually, I used to do that, but haven't for a while, because
everybody wanted the URL to change, so that they could tell from the
URL whether or not it was the version that they had read yet.  So I
create a new resource each time, with a new URL that has the
new draft-id.

   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.

Well, actually, because everybody wants to have the URL indicate
whether it is new or not, I actually *do* update the web page every
time I create a new version, with the new URL.  A *very* key point
here is that it would do me no good to have the versioning system
make up a name for the new document.  In order for it to be human
meaningful, it is essential that I come up with the new name
using a naming scheme meaningful to my readers, and *not* some
id that the versioning system makes up for me.

So in my case, all I need is for the COPY to automatically set
the DAV:precursor-set property of my new document, and I'd be all set.

   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.

Yes, I did that once or twice, and then of course, those were the
times when someone in a different time zone downloaded the version as
soon as I deposited it, and then did a full review, carefully indexing
each comment to the appropriate section number.  Unfortunately, the
"minor fixes" involved swapping a few sections, which then confused
everone who then downloaded the "updated" version and tried to match it up
with the review (wasn't that fun, Tim? :-).

After that experience, I *never* publish a version without updating the
"label" I attach to the version, even if it is just a few hours later
that same night.  Now if the versioning system stored an *accurate*,
*reliable* version id with the resource I published, I *could* just
update the document in place, and whenever there was a collision such
as above, say "well, what was the version URL for the one you downloaded?".

Hey, I *really* like this scenario (:-).

   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.

I'm all for power in the hands of the author (being an author :-),
but I can do all that today.  I can make up human meaningful URL's,
and copy contents to them whenever I want.  What I *can't* do is
reliably track where those contents came from.

   -----------

   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.

Sure.  With the new flag to CHECKIN and DAV:auto-version, you can
delete the previous version whenever you create 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!).

Sure.  Note that "create a new version and delete the previous
version" can be implemented simply as an overwrite, *except* a new
version URL must be generated for the new version.  The "append GUID"
technique described earlier in this thread does that just fine, with
minimal overhead on the server (just need to store the GUID as a
property of the version).

    - It is sometimes interesting to view past versions of a document.

No argument there.

    - Labels are too complicated to be used by simple document applications
   (e.g. Word)

Fair enough.  Please forget my "use a label" suggestion from before.
Replace that with "add a delete predecessor argument to checkin"
suggestion (Greg is the expert at forgetting bad suggestions from
Geoff, so ask him how if you have any difficulty :-).

    - Labelled versions aren't interoperably expressible in URLs

Yup, those labels were a bad suggestion (:-).

    - Some of the clients viewing these documents will be simple web
   browsers.

That should be fine (assuming you forget about my labels suggestion :-).

   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.

Or equivalently, every new version can auto-delete its predecessor.

   Human-readable version URLs

You bet.

   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.

You've got human-readable non-version-controlled URL's,
and human-readable version-controlled resource URL's.
Make one of those whenever you need to make something human
meaningful.  Why do you need *another* way of doing the same
thing?

   Conclusion
   ----------

   Core versioning is nearly capable of fulfilling this scenario.  What is
   desirable/required:
    - Version URLs may be re-used

Doesn't follow from any of the above.  Given the damage to
interoperability of making this move, I'd make it a very last resort
(and I need to be convinced that the first or second resort won't
work before ending up at the last resort :-).

    - Mutability can be supported by a core server.

Sure.  You don't even need a versioning server to get mutability ...
just HTTP and PUT get you that.

   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

OK, I guess we could totally throw out everything we've done, and
start from scratch, but that doesn't seem to be the most expeditious
way to get through last call (:-).

   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.

Well, before we do anything drastic, let's see if the "delete previous"
flag to CHECKIN and DAV:auto-version suffice.

Cheers,
Geoff

Received on Friday, 5 January 2001 15:50:08 UTC