svn commit: r938230 - /subversion/trunk/notes/wc-ng/modularization

[hw...@apache.org]

Author: hwright
Date: Mon Apr 26 20:42:56 2010
New Revision: 938230

URL: http://svn.apache.org/viewvc?rev=938230&view=rev
Log:
* notes/wc-ng/modularization:
  Mostly rewrite, reflecting the State of the World, as well as some other
  potential ideas.

Modified:
    subversion/trunk/notes/wc-ng/modularization

Modified: subversion/trunk/notes/wc-ng/modularization
URL: http://svn.apache.org/viewvc/subversion/trunk/notes/wc-ng/modularization?rev=938230&r1=938229&r2=938230&view=diff
==============================================================================
--- subversion/trunk/notes/wc-ng/modularization (original)
+++ subversion/trunk/notes/wc-ng/modularization Mon Apr 26 20:42:56 2010
@@ -6,67 +6,67 @@ Modularization of Code in WC-NG
 such.  I'll leave that change until such time as we do the doc cleanup in
 that library.
 
-Update (2009-05-10): this section is completely out of date. wc-ng has
-  not used this approach in its development. The primary "new" API
-  layer is wc_db, and the redevelopment focuses around that.
-###GJS: note that hwright has suggested we may want to find lines of
-  division within wc_db. it is already quite large, and growing weekly.
-
 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.
 
-For now, these APIs can be separated:
+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:
 
- - the public API (presumably not to be used by any internal
-     processing, but presents functionality to working copy users)
-#####XBC This is really required of all our module public APIs.
- - tree administration API (required for BASE, TARGET and WORKING)
-     Admins which files are part of the tree, which ones map to
-     which repositories and which textbase / propbase files belong
-     to which local files. [should provide checkpointing functionality
-     for use with transactional tree modifications API]
- - tree access API (required for BASE, WORKING, TARGET and ACTUAL)
-     Gives access to the content of the nodes in a tree
-       - props
-       - text bases (for files)
-       - child nodes (for directories)
- - transactional tree modifications API (applicable to all trees,
-     ###EHU do we provide the same interface to BASE/WORKING as for ACTUAL?)
- - tree transformation (required for update/switch/merge updating
-     BASE, WORKING and ACTUAL), meaning all of tree changes, file
-     changes and metadata changes
- - Working-copy changedness detection API
- - Metadata access API (used by tree administration module(s))
- - Event hooks (in order to be able to implement different
-   timestamp-setting strategies and possibly more)
-
-These APIs will be implemented by these (currently known) modules:
-
- - tree administration
-   * wc_adm
- - tree access
-   * wc_acc
- - transactional tree modifications
-   * wc_log
- - tree transformation
-   * wc_trans
- - working copy changedness detection
-   wc_detect vtable-based API implemented by these modules:
-     * tree crawler ('inspired' by wc-1.0)
-     * tree marker (inspired by 'p4 edit')
- - metadata access API
-   wc_macc vtable-based API implemented by these modules:
-     * tree spread ('inspired' by wc-1.0)
-     * tree root (storing all metadata in the tree root (think darcs))
-     * central depot (storing 'somewhere' locally, possibly $HOME)
-        this central store would open up the possibility to share
-        text bases/prop bases across checkouts
-     * non-local (retrieving all text and prop-bases from the server,
-        except for a number of cached ones) ###EHU: maybe this is
-        orthogonal to the question where metadata is stored: in all
-        situations, you *could* choose not to keep local copies
  - Event hooks for the union of all paths in (BASE, WORKING)
    wc_hook event based single-callback API
    for e.g. these events:
@@ -79,36 +79,3 @@ These APIs will be implemented by these 
        (+ lock can't be acquired [in order to 'unprotect'
            svn:needs-lock protected files which have been removed
            from the repository?])
-   to be implemented by these modules:
-     * use-commit-times
-     * versioned-mtimes
-     * versioned-execute-perm
-     * versioned-other-unix-perms
-    (* versioned-windows-perms?)
-     * needs-lock-updater
-
-Justification for the large number of modules, with a modest number
-of different APIs is that the problem is really quite complex as shown
-earlier in this document.
-
-Over the years, a large number of use cases have developed around
-Subversion where different user groups have shown very valid use cases
-for conflicting behaviours.  Presumably, most of these we want to
-retain.  Some of the unimplemented ones have open issues indicating
-there's at least an active interest.  In order to prevent locking out
-some of the current use cases adding support for the open issues, we
-need a flexible modularized model.  This model will also prevent that
-we'll end up duplicating lots of code to support the different use cases.
-#####XBC Such flexibility will bring the WC to the kind of
-         purgatory the RA layers are in. We promise feature and semantics
-         parity between them, and the result is that even a small change
-         in that layer requires knowledge of three different protocols
-         and four different implementations.
-
-Given the assumption of 'little code duplication', the choice for
-having several modules which implement the same API (vtable) is
-justifiable.
-
-###GJS: disagree. I plan to have just one library and no plans for
-   vtables. there is very little need for distinct implementations, as
-   far as I can tell.