webdav-general-summary

linux subdivision ying gai ke yi le ba

If the server supports the 'auto-versioning' feature, then all
resources gain a new live property called 'DAV:auto-version'.  The
value of this property indicates how the server should behave when a
non-deltaV client does an ignorant PUT or PROPPATCH on a resource.  I
won't go into detail, but there are many possible behaviors:

  * do an implicit (auto-) CHECKOUT and CHECKIN.
  * auto-CHECKOUT, and wait for a lock to vanish before auto-CHECKIN.
  * same as above, but if not locked, wait for an explicit CHECKIN.
  * require a lock.  LOCK causes auto-CHECKOUT, UNLOCK causes auto-CHECKIN.



Basic Features
==============

DeltaV has a bunch of "basic features", and a bunch of "advanced
features".  Here are the basic features, in a nutshell.


* Version Control feature

    * new VERSION-CONTROL method to create a VCR.

    * resources gain a whole bunch of new live props (not all listed
      here), such some of which include DAV:checked-[in|out],
      DAV:auto-version, DAV:comment, the author.  VRs have properties
      that describe lists of successor and predecessor VRs.

    * new REPORT method.  two 'standard' reports are defined, but
      custom reports can be created.


* Checkout-in-place feature
 
    * new CHECKOUT, CHECKIN, UNCHECKOUT methods, which are able to
      modify VCRs in-place.


* Version History feature

    * version histories become tangible URLs.  introduce new dav
      resourcetype called 'DAV:version-history'.

    * all VCRs and VR's gain a 'DAV:version-history' prop that points
      to their history resource.

    * a version-history has a 'DAV:version-set' property that lists
      all VRs it contains, and a 'DAV:root-version' that points to the
      very first VR in the history.

    * a special REPORT allows one to convert a version-history URL
      into the VCR it represents.  (i.e. reverse-lookup.)


* Workspace feature

    * MKWORKSPACE creates a server-side working area.  an OPTIONS
      request can tell you where the client is allowed to do this.

    * the workspace resource has a property that lists all the
      resources it contains.  regular resources have a property
      indicating what workspace they're in.

    * The workspace can hold unversioned items put there by PUT & MKCOL.
      It can hold VCRs via CHECKOUT.

    * Special:  the VERSION-CONTROL method can create a *new* VCR from
      a history.  If two people both CHECKIN VCRs created from the
      same history resource, then poof... the history develops forks!


* Update feature

    * UPDATE method is able to tweak a VCR to "point" to a new VR.
      Very simple!


* Label feature

    * LABEL method allows you to attach a human-readable name to a
      particular VR.  

    * Each VR can have many names.  They're listed in a
      'DAV:label-name-set' property.

    * New http request header, "Label:", can be used to target
      a specific VR of a VCR.  This works when doing a GET of a VCR.
      It also works as you think on COPY, CHECKOUT, UDPATE, etc.


* Working Resource feature

    * This feature essentially allows client-side working copies to
      synchronize their data with the server.

    * all VRs gain two properties that control whether or not
      histories can (or should) contain forks.

    * a CHECKOUT of a VR creates a temporary 'working resource' (WR),
      which can then be modified.  When the WR is checked in, a new VR
      is created as usual, the WR vanishes, and the VCR is updated to
      point to the VR as usual.

    * note that this technique is an alternative to the
      Checkout-in-place feature, whereby VCRs are directly checked out
      and modified.



Advanced Features
=================

The advanced features of deltaV introduce a bunch of new concepts.
Here are the fundamentals.

[Whenever I say, "points to", I'm talking about some object leading to
another object via a specific property.]

* A "configuration" is a set of VCRs.  In particular, it contains a
  "root collection" which organizes the VCRs in some way.

  Note that this is _different_ than a versioned collection.  The main
  difference is that a collection is a *single* resource which
  contains dead-props and some directory-entries; its VRs just capture
  various states of the props and dirents.  But it's just ONE
  resource.  A configuration, however, is a SET of VCRs.  The VCRs may
  not necessarily be related to each other, either.  A configuration
  is a flexible thing -- it's VCRs can be tweaked to point to
  different VRs, however you want, with no versioning happening in the
  background.  A collection, on the other hand, has a static set of
  dirents; to change them, you have to do a CHECKOUT, CHECKIN, which
  results in a new, static collection VR.

* A "baseline" is a special kind of resource which remembers this
  state of a configuration... it knows exactly which VR each VCR in
  the configuration should point to.  Just like a VR is a 'snapshot'
  of a VCR, a baseline is a 'snapshot' of the configuration.  And just
  like a VR, a baseline can have a human label too.
  
* Another kind of resource is a "version controlled configuration", or
  VCC.  This resource floats out in space;  its sole purpose is to
  magically connect a configuration to a baseline.   Specifically,
  each VCR in the configuration points to the VCC, and the VCC points
  to a baseline.

  And here's the usual magic: if you make the VCC point to a different
  baseline, then poof, the whole configuration suddenly switches to
  the baseline.  (That is, all of the configuration's VCRs suddenly
  point to the specific VRs of the baseline.)

* Finally, it's worth mentioning that a baseline resource points to a
  "baseline collection" resource.  This collection is a tree made up
  of the VRs in the baseline, easily browseable.  You can think of it
  as a "what-if" sort of preview -- i.e. "what would the configuration
  look like if I made its VCC point to this baseline?"  It also means
  people can view a baseline in action, *without* having to tweak a
  VCC, which might require write access of some kind.


Got all that?  Good.  Make some pictures.  :-)


How to create new baselines
===========================

The "in-place" method:

   Get this.  A VCC is really just a special kind of VCR!  But it's a
   VCR which represents the *whole state* of a configuration.  Just
   like a normal VCR, the VCC's "DAV:checked-in" property points to a
   baseline, which just a special kind of VR.

   That means you can do a CHECKOUT of the VCC in-place... then tweak
   the configuration to point to a new set of VR's... then CHECKIN the
   VCC.  Poof, a new baseline is created which captures your new
   configuration state.  And the VCC now points to that new baseline.

The "working resource" method:   

   Okay, so a baseline is a special kind of VR.  Fine, so we do a
   CHECKOUT of it, and get a "working baseline", which a special kind
   of WR.  

   Now, assuming you're using this method all around, you checkout the
   configuration's various VRs as WRs, modify the WRs, and check them
   back in to create new VRs.  Finally, you CHECKIN the working
   baseline, which creates a new baseline that captures the state of
   the configuration.  (The working baseline isn't something you tweak
   directly;  it's more like a token used at CHECKIN time.)


How Merging Works... at least for SVN.
=================

The deltaV MERGE command is very fancy.  It tracks merge ancestors in
properties, and sets flags for clients to manually resolve conflicts
on the server.

Subversion uses MERGE in a simpler way:

  1. We checkout a bunch of VRs into an activity, and patch them as a
     bunch of WRs.

  2. We checkout a "working baseline" into the activity, from whatever
     baseline represents the HEAD svn revision.

  3. We issue a MERGE request with the activity as the source.

     By definition, this causes the whole activity to be
     auto-checked-in.  First each WR in the activity is checked-in,
     causing the configuration to morph.  Then the working-baseline in
     the activity is checked-in, which creates a new baseline that
     captures the configuration state.

Of course, mod_dav_svn doesn't actually do all the checkin stuff;  but
what's important is that the *result* of the MERGE is exactly as IF
all this stuff had happened.  And that's all that matters.