changeset 16728:99f369f5a8db

merge with crew

--- a/mercurial/phases.py	Tue May 15 07:00:55 2012 +0200
+++ b/mercurial/phases.py	Tue May 15 07:01:35 2012 +0200
@@ -6,8 +6,8 @@
                    Logilab SA        <[e-mail]>
                    Augie Fackler     <[e-mail]>
 
-    This software may be used and distributed according to the terms of the
-    GNU General Public License version 2 or any later version.
+    This software may be used and distributed according to the terms
+    of the GNU General Public License version 2 or any later version.
 
     ---
 
@@ -17,17 +17,17 @@
 Basic Concept
 =============
 
-A 'changeset phases' is an indicator that tells us how a changeset is
-manipulated and communicated. The details of each phase is described below,
-here we describe the properties they have in common.
+A 'changeset phase' is an indicator that tells us how a changeset is
+manipulated and communicated. The details of each phase is described
+below, here we describe the properties they have in common.
 
-Like bookmarks, phases are not stored in history and thus are not permanent and
-leave no audit trail.
+Like bookmarks, phases are not stored in history and thus are not
+permanent and leave no audit trail.
 
-First, no changeset can be in two phases at once. Phases are ordered, so they
-can be considered from lowest to highest. The default, lowest phase is 'public'
-- this is the normal phase of existing changesets. A child changeset can not be
-in a lower phase than its parents.
+First, no changeset can be in two phases at once. Phases are ordered,
+so they can be considered from lowest to highest. The default, lowest
+phase is 'public' - this is the normal phase of existing changesets. A
+child changeset can not be in a lower phase than its parents.
 
 These phases share a hierarchy of traits:
 
@@ -36,25 +36,26 @@
     draft:               X
     secret:
 
-local commits are draft by default
+Local commits are draft by default.
+
+Phase Movement and Exchange
+===========================
 
-Phase movement and exchange
-============================
-
-Phase data are exchanged by pushkey on pull and push. Some server have a
-publish option set, we call them publishing server. Pushing to such server make
-draft changeset publish.
+Phase data is exchanged by pushkey on pull and push. Some servers have
+a publish option set, we call such a server a "publishing server".
+Pushing a draft changeset to a publishing server changes the phase to
+public.
 
 A small list of fact/rules define the exchange of phase:
 
 * old client never changes server states
 * pull never changes server states
-* publish and old server csets are seen as public by client
+* publish and old server changesets are seen as public by client
+* any secret changeset seen in another repository is lowered to at
+  least draft
 
-* Any secret changeset seens in another repository is lowered to at least draft
-
-
-Here is the final table summing up the 49 possible usecase of phase exchange:
+Here is the final table summing up the 49 possible use cases of phase
+exchange:
 
                            server
                   old     publish      non-publish
@@ -81,18 +82,19 @@
     * N = new/not present,
     * P = public,
     * D = draft,
-    * X = not tracked (ie: the old client or server has no internal way of
-          recording the phase.)
+    * X = not tracked (i.e., the old client or server has no internal
+          way of recording the phase.)
 
     passive = only pushes
 
 
     A cell here can be read like this:
 
-    "When a new client pushes a draft changeset (D) to a publishing server
-    where it's not present (N), it's marked public on both sides (P/P)."
+    "When a new client pushes a draft changeset (D) to a publishing
+    server where it's not present (N), it's marked public on both
+    sides (P/P)."
 
-Note: old client behave as publish server with Draft only content
+Note: old client behave as a publishing server with draft only content
 - other people see it as public
 - content is pushed as draft
 
@@ -110,7 +112,7 @@
 def _filterunknown(ui, changelog, phaseroots):
     """remove unknown nodes from the phase boundary
 
-    Nothing is lost as unknown nodes only hold data for their descendants
+    Nothing is lost as unknown nodes only hold data for their descendants.
     """
     updated = False
     nodemap = changelog.nodemap # to filter unknown nodes
@@ -262,8 +264,8 @@
 def advanceboundary(repo, targetphase, nodes):
     """Add nodes to a phase changing other nodes phases if necessary.
 
-    This function move boundary *forward* this means that all nodes are set
-    in the target phase or kept in a *lower* phase.
+    This function move boundary *forward* this means that all nodes
+    are set in the target phase or kept in a *lower* phase.
 
     Simplify boundary to contains phase roots only."""
     phcache = repo._phasecache.copy()
@@ -271,10 +273,11 @@
     repo._phasecache.replace(phcache)
 
 def retractboundary(repo, targetphase, nodes):
-    """Set nodes back to a phase changing other nodes phases if necessary.
+    """Set nodes back to a phase changing other nodes phases if
+    necessary.
 
-    This function move boundary *backward* this means that all nodes are set
-    in the target phase or kept in a *higher* phase.
+    This function move boundary *backward* this means that all nodes
+    are set in the target phase or kept in a *higher* phase.
 
     Simplify boundary to contains phase roots only."""
     phcache = repo._phasecache.copy()
@@ -282,28 +285,29 @@
     repo._phasecache.replace(phcache)
 
 def listphases(repo):
-    """List phases root for serialisation over pushkey"""
+    """List phases root for serialization over pushkey"""
     keys = {}
     value = '%i' % draft
     for root in repo._phasecache.phaseroots[draft]:
         keys[hex(root)] = value
 
     if repo.ui.configbool('phases', 'publish', True):
-        # Add an extra data to let remote know we are a publishing repo.
-        # Publishing repo can't just pretend they are old repo. When pushing to
-        # a publishing repo, the client still need to push phase boundary
+        # Add an extra data to let remote know we are a publishing
+        # repo. Publishing repo can't just pretend they are old repo.
+        # When pushing to a publishing repo, the client still need to
+        # push phase boundary
         #
-        # Push do not only push changeset. It also push phase data. New
-        # phase data may apply to common changeset which won't be push (as they
-        # are common).  Here is a very simple example:
+        # Push do not only push changeset. It also push phase data.
+        # New phase data may apply to common changeset which won't be
+        # push (as they are common). Here is a very simple example:
         #
         # 1) repo A push changeset X as draft to repo B
         # 2) repo B make changeset X public
-        # 3) repo B push to repo A. X is not pushed but the data that X as now
-        #    public should
+        # 3) repo B push to repo A. X is not pushed but the data that
+        #    X as now public should
         #
-        # The server can't handle it on it's own as it has no idea of client
-        # phase data.
+        # The server can't handle it on it's own as it has no idea of
+        # client phase data.
         keys['publishing'] = 'True'
     return keys