Changeset 20 in tailor

Timestamp:

06/22/04 00:04:51 (9 years ago)

Author:

lele@…

Hash name:

20040621220451-97f81-0a40214a02af731cd80a8b614099b50f2c93d22a

Message:

Documentation

Location:

vcpx

Files:

• source.py (modified) (3 diffs)
• target.py (modified) (2 diffs)

vcpx/source.py

@@ -15 +15 @@
 
 class UpdatableSourceWorkingDir(object):
-    """This is an abstract working dir. Subclasses MUST override at least
-       the _underscoredMethods."""
+    """
+    This is an abstract working dir able to follow an upstream
+    source of `changesets`.
+
+    It has two main functionalities:
+
+    applyUpstreamChangesets
+        to query the upstream server about new changesets and
+        apply them to the working directory
+
+    checkoutUpstreamRevision
+        to extract a new copy of the sources, actually initializing
+        the mechanism.
+      
+    Subclasses MUST override at least the _underscoredMethods.
+    """
 
     def applyUpstreamChangesets(self, root, replay=None):
@@ -56 +70 @@
         """
         Do the actual work of applying the changeset to the working copy.
+
+        Subclasses should reimplement this method performing the
+        necessary steps to *merge* given `changeset`, returning a list
+        with the conflicts, if any.
         """
 
@@ -63 +81 @@
         """
         Extract a working copy from a repository.
+
+        :root: the name of the directory (that should **not** exists)
+               that will contain the working copy of the sources
+
+        :repository: the address of the repository (the format depends on
+                     the actual method used by the subclass)
+
+        :revision: extract that revision/branch
         """
 

vcpx/target.py

@@ -17 +17 @@
 class SyncronizableTargetWorkingDir(object):
     """
-    This is an abstract working dir. Subclasses MUST override at least
-    the _underscoredMethods.
+    This is an abstract working dir usable as a *shadow* of another
+    kind of VC, sharing the same working directory.
+
+    Most interesting entry points are:
+
+    replayChangeset
+        to replay an already applied changeset, to mimic the actions
+        performed by the upstream VC system on the tree such as
+        renames, deletions and adds.  This is an useful argument to
+        feed as `replay` to `applyUpstreamChangesets`
+
+    initializeNewWorkingDir
+        to initialize a pristine working directory tree under this VC
+        system, possibly extracted under a different kind of VC
+    
+    Subclasses MUST override at least the _underscoredMethods.
     """
 
@@ -92 +106 @@
         from some VC repository, add it and all its content to the
         target repository.
+
+        This implementation first runs the given `addentry`
+        *SystemCommand* on the `root` directory, then it walks down
+        the `root` tree executing the same command on each entry
+        excepted the usual VC-specific control directories such as
+        ``.svn``, ``_darcs`` or ``CVS``.
+
+        If this does make sense, subclasses should just call this
+        method with the right `addentry` command.
         """