| -*- 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?]) |