[PATCH] Describing depth/recurse concepts in the RA layer

Karl, Vlad, et at:

Okay, it's not *really* a patch. I was trying to keep my thinking straight
regarding all the depths and recursion flags flying across the RA layer.
The following is what I worked up. Can you guys review it for sanity and
correctness? If it's accurate, I'd like to put this (or something like it)
into the sparse-directories.txt file.

--------------------------------------------------------------------------

PRE-1.5 CLIENTS

  Pre-1.5 clients will never transmit reported depths and never
  transmit a requested depth. But they will (perhaps optionally,
  depending on the RA layer) transmit a requested recurse (either
  'yes' or 'no', with 'yes' being the default).

  When speaking to a pre-1.5 server, what happens happens. It's the past,
  man -- you don't get to define it now.

  When speaking to a 1.5 server, the not-reported depths are treated
  like reported depths of 'infinity', and the recurse 'yes' and 'no'
  map to depths of 'infinity' and 'files', respectively.

1.5 CLIENTS

  1.5 clients will transmit reported depths (with 'infinity' as the
  default) and will transmit a requested depth (with 'unknown' as the
  default). They will also -- for the sake of older, non-depth-aware
  servers -- transmit a requested recurse, mapped from requested
  depths ('empty' or 'files' = no; 'unknown', 'immediates', and
  'infinity' = yes).

  When speaking to a pre-1.5 server, the requested recurse is the only thing
  the server notes, but is obviously more "grainy" than the depth concept.
  The client, therefore, must filter out unwanted data that the server
  transmits.

  When speaking to a 1.5 server, the requested recurse is ignored. A
  requested depth of "unknown" means "only send information about the
  stuff in my report, depth-aware-ily". Other depths are honored by
  the server properly, and the client must handle the transformation of
  any working copy depths from their pre-update to their post-update
  depths and content.

-- 
C. Michael Pilato <cmpilato@collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand