notes/wc-ng/modularization

                                                                -*- Text -*-

Modularization of Code in WC-NG
===============================
###HKW: This section may someday want to live in libsvn_wc/README or some
such.  I'll leave that change until such time as we do the doc cleanup in
that library.

Strict separation must be applied to a number of modules which can be
recognised.  This will help prevent spaghetti code as in wc-1.0 where
one piece of code manipulates paths to a working copy file, its URL
*and* the path to the base file.

To enforce this strict separation, WC-NG is layered using several API levels.
Some of these levels are internal to libsvn_wc, some are (currently) only
exposed to other code within Subversion, while others are meant for public
consumption.  The functions which define an API may be one of two flavors:
 - functions which *do* something (i.e., change the state of the disk or
   database somehow)
 - functions which callers can use to *know* something.
Each API may define and consume have both types of functions.

For extensibility and maintainability, it is recommended that API layers only
expose data structures as opaque types, and then provide the means for
consumers to retrieve the data that interests them.  This helps enforce
loose coupling between layers and code, as well as the API separation defined
above.  Even when technological restrictions are loose enough to permit
direct access to a data structure, refrain from doing so.

It is *highly recommended* that future extensions to libsvn_wc maintain this
paradigm, as it helps eliminate confusion, such as combined input/output
parameters and state changes within the working copy.  We'd like to think we
learned our lesson with wc-1; don't make the same mistake again!

For now, these API layers can be separated thusly:

 - the wc_db-internal API
   * ### HKW: Still working on this.  Right now, wc_db.c is one massive
     power plant of a file, and it just Ought Not To Be. :(
 - the library-internal
   * svn_wc__db_ functions, which handle access and changes to the working
     copy data store.  See libsvn_wc/wc_db.h for a more detailed subdivision.
   * svn_wc__wq_ functions, which replace the old 'loggy' concept with more
     high-level APIs.
   * pristine handling?
 - the Subversion-public API
   * various svn_wc__node_ functions, used to obtain (read-only) information
     about nodes in the working copy
 - the world-public API
   * any existing non-deprecated svn_wc_ APIs
   * the APIs surrounding the WC context object (svn_wc_context_t)

Additional layering be yet be needed and developed, but as of this writing,
these are the current API layers within, and exported by, libsvn_wc.

(Note: there is some talk of whether or not libsvn_wc should itself be folded
into libsvn_client.  The debate as to the practicalities of such a suggestion
is left as an exercise for the reader.)


File Descriptions
-----------------


Historical Information
----------------------
These APIs are not currently implemented, and there exist no plans for such,
but the ideas may still be of value:

 - Event hooks for the union of all paths in (BASE, WORKING)
   wc_hook event based single-callback API
   for e.g. these events:
        + props updated
        + base text updated
        + wc file updated
        + update completed
        + lock acquired
        + lock released
       (+ lock can't be acquired [in order to 'unprotect'
           svn:needs-lock protected files which have been removed
           from the repository?])