[Checkins] SVN: z3c.vcsync/trunk/src/z3c/vcsync/ Move some useful
text out of README.txt into svn.txt. README.txt will become
Martijn Faassen
faassen at infrae.com
Mon Apr 21 15:06:11 EDT 2008
Log message for revision 85568:
Move some useful text out of README.txt into svn.txt. README.txt will become
an internal set of tests, and svn.txt will soon become the new README.txt.
Changed:
U z3c.vcsync/trunk/src/z3c/vcsync/README.txt
U z3c.vcsync/trunk/src/z3c/vcsync/svn.txt
-=-
Modified: z3c.vcsync/trunk/src/z3c/vcsync/README.txt
===================================================================
--- z3c.vcsync/trunk/src/z3c/vcsync/README.txt 2008-04-21 18:59:13 UTC (rev 85567)
+++ z3c.vcsync/trunk/src/z3c/vcsync/README.txt 2008-04-21 19:06:11 UTC (rev 85568)
@@ -1,62 +1,9 @@
-Version Control Synchronization
-===============================
+Internal tests
+==============
-This package contains code that helps with handling synchronization of
-persistent content with a version control system. This can be useful
-in software that needs to be able to work offline. The web application
-runs on a user's laptop that may be away from an internet
-connection. When connected again, the user syncs with a version
-control server, receiving updates that may have been made by others,
-and committing their own changes.
+This document contains a number of internal tests of the
+synchronization facility.
-The synchronization sequence (ISequences) is as follows (example given
-with SVN as the version control system):
-
- 1) save persistent state (IState) to svn checkout (ICheckout) on the
- same machine as the Zope application.
-
- 2) ``svn up``. Subversion merges in changed made by others users
- that were checked into the svn server.
-
- 3) Any svn conflicts are automatically resolved.
-
- 4) reload changes in svn checkout into persistent Python objects
-
- 5) ``svn commit``.
-
-This is all happening in a single step. It can happen over and over
-again in a reasonably safe manner, as after the synchronization has
-concluded, the state of the persistent objects and that of the local
-SVN checkout will always be perfectly in sync.
-
-During synchronizing, the system tries to take care only to
-synchronize those objects and files that have changed. That is, in
-step 1) only those objects that have been modified, added or removed
-will have an effect on the checkout. In step 4) only those files that
-have been changed, added or removed on the filesystem due to the
-``up`` action will change the persistent object state.
-
-SVN difficulties
-----------------
-
-Changing a file into a directory with SVN requires the following
-procedure::
-
- * svn remove file
-
- * svn commit file
-
- * svn up
-
- * mdkir file
-
- * svn add file
-
-If during the serialization procedure a file changed into a directory,
-it would require an ``svn up`` to be issued during step 1. This is too
-early. As we see later, we instead ask the application developer to
-avoid this situation altogether.
-
To start
--------
@@ -117,32 +64,6 @@
Export persistent state to version control system checkout
----------------------------------------------------------
-As part of the synchronization procedure we need the ability to export
-persistent python objects to the version control checkout directory in
-the form of files and directories.
-
-Content is represented by an ``IState``. This supports two methods:
-
-* ``objects(revision_nr)``: any object that has been modified since
- revision_nr. Returning 'too many' objects (objects that weren't
- modified) is safe, though less efficient as they will then be
- re-exported.
-
- Typically in your application this would be implemented as the
- result of a catalog search.
-
-* ``removed(revision_nr)``: any path that has had an object removed
- from it since revision_nr. It is safe to return paths that have
- been removed and have since been replaced by a different object with
- the same name. It is also safe to return 'too many' paths, though
- less efficient as the objects in these paths may be re-exported
- unnecessarily.
-
- Typically in your application you would maintain a list of removed
- objects by hooking into IObjectRemovedEvent and recording the paths
- of all objects that were removed. After an export it is safe to
- purge this list.
-
Let's imagine we have this object structure consisting of a container
with some items and sub-containers in it::
@@ -221,8 +142,7 @@
Modifying an existing checkout
------------------------------
-Now let's assume that the version control checkout is that as
-generated by step 1a). We will now change some data in the ZODB again.
+We will now change some data in the ZODB again.
Let's add ``hoi``::
Modified: z3c.vcsync/trunk/src/z3c/vcsync/svn.txt
===================================================================
--- z3c.vcsync/trunk/src/z3c/vcsync/svn.txt 2008-04-21 18:59:13 UTC (rev 85567)
+++ z3c.vcsync/trunk/src/z3c/vcsync/svn.txt 2008-04-21 19:06:11 UTC (rev 85568)
@@ -1,10 +1,50 @@
-SVN integration
-===============
+Version Control Synchronization
+===============================
-z3c.vcsync can work with SVN as a backend. At the time of writing,
-this is the only version control backend that is supported. Here we
-show how to integrate your aplication with SVN.
+This package contains code that helps with handling synchronization of
+persistent content with a version control system.
+This can be useful in software that needs to be able to work
+offline. The web application runs on a user's laptop that may be away
+from an internet connection. When connected again, the user syncs with
+a version control server, receiving updates that may have been made by
+others, and committing their own changes.
+
+Another advantage is that the version control system always contains a
+history of how content developed over time. The version-control based
+content can also be used for other purposes independent of the
+application.
+
+While this package has been written with other version control systems
+in mind, it has only been developed to work with SVN so far. Examples
+below are all given with SVN.
+
+The synchronization sequence is as follows:
+
+1) save persistent state (IState) to svn checkout (ICheckout) on the
+ same machine as the Zope application.
+
+2) ``svn up``. Subversion merges in changed made by others users that
+ were checked into the svn server.
+
+3) Any svn conflicts are automatically resolved.
+
+4) reload changes in svn checkout into persistent Python objects
+
+5) ``svn commit``.
+
+This is all happening in a single step. It can happen over and over
+again in a reasonably safe manner, as after the synchronization has
+concluded, the state of the persistent objects and that of the local
+SVN checkout will always be in sync.
+
+During synchronisation, the system tries to take care only to
+synchronize those objects and files that have changed. That is, in
+step 1) only applies those objects that have been modified, added or
+removed will have an effect on the checkout. In step 4) only those
+files that have been changed, added or removed on the filesystem due
+to the ``up`` action will change the persistent object state.
+
The tree to synchronize
-----------------------
@@ -44,17 +84,37 @@
>>> data['sub'] = Container()
>>> data['sub']['qux'] = Item(payload=3)
-The tree is represented by a special ``IState`` object, which allows
-the synchronizer to ask which objects have changed (or been added)
-since the last synchronization (when ``last_revision_nr`` is updated),
-and which objects have been removed (or moved from their original
-location). In a real application you could implement this using an
-index on the revision nr, so that they can be looked up quickly. Event
-handlers for ``IObjectMovedEvent`` and ``IObjectRemovedEvent`` can be
-used to track which objects were removed. Here we will use a simpler,
-less efficient, implementation that goes through the entire tree to
-find changes::
+As part of the synchronization procedure we need the ability to export
+persistent python objects to the version control checkout directory in
+the form of files and directories.
+
+Content is represented by an object that provides ``IState``. Two methods
+need to be implemented:
+* ``objects(revision_nr)``: any object that has been modified (or
+ added) since the synchronization for ``revision_nr``. Returning 'too
+ many' objects (objects that weren't modified) is safe, though less
+ efficient as they will then be re-exported.
+
+ Typically in your application this would be implemented by doing
+ a catalog search, so that they can be looked up quickly.
+
+* ``removed(revision_nr)``: any path that has had an object removed
+ from it since revision_nr. It is safe to return paths that have
+ been removed and have since been replaced by a different object with
+ the same name. It is also safe to return 'too many' paths, though
+ less efficient as the objects in these paths may be re-exported
+ unnecessarily.
+
+ Typically in your application you would maintain a list of removed
+ objects by hooking into ``IObjectMovedEvent`` and
+ ``IObjectRemovedEvent`` and recording the paths of all objects that
+ were moved or removed. After an export it is safe to purge this
+ list.
+
+In this example, we will use a simpler, less efficient, implementation
+that goes through the entire tree to find changes::
+
>>> from zope.interface import implements
>>> from z3c.vcsync.interfaces import IState
>>> class TestState(object):
@@ -227,5 +287,3 @@
2
>>> print wc.join('root').join('sub').join('qux.test').read()
3
-
-
\ No newline at end of file
More information about the Checkins
mailing list