[Zope-CVS] SVN: zversioning/trunk/src/versioning/README.txt another intermediate version

[Grégoire Weber]

Log message for revision 28078:
  another intermediate version

Changed:
  U   zversioning/trunk/src/versioning/README.txt

-=-
Modified: zversioning/trunk/src/versioning/README.txt
===================================================================
--- zversioning/trunk/src/versioning/README.txt	2004-10-13 13:30:21 UTC (rev 28077)
+++ zversioning/trunk/src/versioning/README.txt	2004-10-13 13:32:32 UTC (rev 28078)
@@ -2,6 +2,8 @@
 Versioning
 ==========
 
+Setup Stuff
+-----------
 
 In the following we take a simple folder tree with the following structure
 as an example :
@@ -42,19 +44,26 @@
   >>> db_root = buildDatabaseRoot()
   >>> db_root["sample"] = sample 
 
+
+CopyModifyMergeRepository explained
+-----------------------------------
+
 In this architecture we can choose between several repositories. We take a
 CopyModifyMergeRepository without check in and check out as an example.
 
+First lets configure the various component needed (what 'configure.zcml' 
+usually does for us):
+
   >>> from zope.app.tests import ztapi
-  >>> from versioning import interfaces, policies, storage
+  >>> from versioning import interfaces, repository, policies, storage
 
-First lets configure the 'IHistoryStorage' utility being responsible
-for the storage of the objects histories:
+Configure the 'IHistoryStorage' utility being responsible for the storage 
+of the objects histories:
 
   >>> ztapi.provideUtility(interfaces.IHistoryStorage,
   ...                      storage.SimpleHistoryStorage())
 
-Then we need a 'IVersionableAspects' multi adapter beeing responsible
+We also need a 'IVersionableAspects' multi adapter beeing responsible
 for the versioning policy (what is versioned and how (not storage)).
 
   >>> ztapi.provideAdapter((interfaces.IVersionable, 
@@ -62,15 +71,28 @@
   ...                      interfaces.IVersionableAspects,
   ...                      policies.VersionableAspectsAdapter)
 
+Register a 'ICheckoutAware' adapter to a 'IHistoryStorage' that 
+handles the checkout/checkin status for the repository.
+
+  >>> ztapi.provideAdapter(interfaces.ICheckoutAware,
+  ...                      interfaces.IHistoryStorage,
+  ...                      repository.DummyCheckoutAware)
+
+Let's now build the repository:
+
   >>> from versioning.repository import CopyModifyMergeRepository
   >>> repository = buildRepository(CopyModifyMergeRepository)
 
-An object that isn't 'IVersionable' can't be put under version control:
+An object that isn't 'IVersionable' can't be put under version control.
+Applying version control should raise an exception:
 
   >>> repository.applyVersionControl(a)
   Traceback (most recent call last):
   RepositoryError: This resource cannot be put under version control.
 
+So let us attach marker interfaces to the object before putting them
+under version control:
+
   >>> from versioning.tests.repository_setup import instanceProvides
   >>> instanceProvides(sample, interfaces.IVersionable)
   >>> instanceProvides(a, interfaces.IVersionable)
@@ -78,11 +100,13 @@
   >>> instanceProvides(c, interfaces.IVersionable)
 
 The chosen 'IHistoryStorage' component expects the objects having
-a '_p_oid'
+a '_p_oid'. 
+XXX We know this is an implementation detail. We probably should think
+more about this and then talk about this in the interfaces.
 
   >>> util.commit()
 
-Now we can put our example data under version control:
+Now let's put our example data under version control:
 
   >>> repository.applyVersionControl(sample)
   >>> repository.applyVersionControl(a)