[PATCH] Clarify how wcprops should be used (was: Re: simple tree conflict detection)

On Wed, Nov 21, 2007 at 12:53:14PM -0800, Karl Fogel wrote:
> "Erik Huelsmann" <ehuels@gmail.com> writes:
> > Right, that's when you look strictly at the API, but if you look at
> > the larger design (I'm not saying I know where that picture is stored,
> > so, I'm not sure how you could do that...) you'll see they have very
> > differing functions/goals.
> >
> > For the long term solution I'd like to keep the fix for tree conflicts
> > as close to the original intentions of the libsvn_wc structure
> > (meaning that I'd like to admin wc status in .svn/entries if at all
> > possible).
>
> I think Erik is right; it's just a bug if the internal documentation
> doesn't make clear how wcprops are meant to be used. New working copy
> features should use the entries file, not overload wcprops (which are,
> frankly, a bit of a kludge in the first place).

What about this then?

[[[
* subversion/libsvn_wc/README:
  Explain that wcprops should only be used by the networking
  layer, and should never be used to store working copy metadata.
]]]

Index: subversion/libsvn_wc/README
===================================================================
--- subversion/libsvn_wc/README (revision 27979)
+++ subversion/libsvn_wc/README (working copy)
@@ -285,11 +285,13 @@
 
 'all-wcprops/':
    Some properties are never seen or set by the user, and are never
- stored in the repository filesystem. They are created by the
- networking layer (DAV right now) and need to be secretly saved and
- retrieved, much like a web browser stores "cookies". Special wc
- library routines allow the networking layer to get and set these
- properties.
+ stored in the repository filesystem. They are created and used
+ exclusively by the networking layer (DAV right now) and need to
+ be secretly saved and retrieved, much like a web browser stores
+ "cookies". Special wc library routines allow the networking layer
+ to get and set these properties. By design, working copy metadata
+ used by libsvn_wc itself should always be stored in the entries file,
+ never in wcprops.
 
    Note that because these properties aren't being versioned, we don't
    bother to keep pristine forms of them in a 'base' area.

-- 
Stefan Sperling <stsp@elego.de>                 Software Developer
elego Software Solutions GmbH                            HRB 77719
Gustav-Meyer-Allee 25, Gebaeude 12        Tel:  +49 30 23 45 86 96 
13355 Berlin                              Fax:  +49 30 23 45 86 95
http://www.elego.de                 Geschaeftsfuehrer: Olaf Wagner