# HG changeset patch
# User Matt Mackall <mpm@selenic.com>
# Date 2012-01-26 17:23:14
# Node ID 0455463655e0f289a2f19a8dd2f2fb8567c9e53c
# Parent  b006735cf57a5c939a0066c17fa7301eb6640062

help: add phases topic

diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -73,6 +73,7 @@ helptable = sorted([
    (["glossary"], _("Glossary"), loaddoc('glossary')),
    (["hgignore", "ignore"], _("syntax for Mercurial ignore files"),
     loaddoc('hgignore')),
+   (["phases"], _("Working with Phases"), loaddoc('phases')),
 ])
 
 # Map topics to lists of callable taking the current topic help and
diff --git a/mercurial/help/phases.txt b/mercurial/help/phases.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/help/phases.txt
@@ -0,0 +1,61 @@
+What are phases?
+----------------
+
+Phases are a system for tracking which changesets have been or should
+be shared. This helps prevent common mistakes when modifying history
+(for instance, with the mq or rebase extensions).
+
+Each changeset in a repository is in one of the following phases:
+
+ - public : changeset is visible on a public server
+ - draft : changeset is not yet published
+ - secret : changeset should not be pushed, pulled, or cloned
+
+These phases are ordered (public < draft < secret) and no changeset
+can be in a lower phase than its ancestors. For instance, if a
+changeset is public, all its ancestors are also public. Lastly,
+changeset phases only be changed towards the public phase.
+
+How are phases managed?
+-----------------------
+
+For the most part, phases should work transparently. By default, a
+changeset is created in the draft phase and is moved into the public
+phase when it is pushed to another repository.
+
+Once changesets become public, extensions like mq and rebase will
+refuse to operate on them to prevent creating duplicate changesets.
+Phases can also be manually manipulated with the :hg:`phase` command
+if needed. See :hg:`help -v phase` for examples.
+
+Phases and servers
+------------------
+
+Normally, all servers are ``publishing`` by default. This means::
+
+ - all draft changesets that are pulled or cloned appear in phase
+ public on the client
+
+ - all draft changesets that are pushed appear as public on both
+ client and server
+
+ - secret changesets are neither pushed, pulled, or cloned
+
+.. note::
+  Pulling a draft changeset from a publishing server does not mark it
+  as public on the server side due to the read-only nature of pull.
+
+Sometimes it may be desirable to push and pull changesets in the draft
+phase to share unfinished work. This can be done by setting a
+repository to disable publishing in its configuration file::
+
+  [phases]
+  publishing = False
+  
+See :hg:`help config` for more information on config files.
+
+.. note::
+  Servers running older versions of Mercurial are treated as
+  publishing.
+
+See :hg:`help phase` for information on manually manipulating phases.
diff --git a/tests/test-globalopts.t b/tests/test-globalopts.t
--- a/tests/test-globalopts.t
+++ b/tests/test-globalopts.t
@@ -347,6 +347,7 @@ Testing -h/--help:
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
    patterns      File Name Patterns
+   phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
@@ -430,6 +431,7 @@ Testing -h/--help:
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
    patterns      File Name Patterns
+   phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -119,6 +119,7 @@ Short help:
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
    patterns      File Name Patterns
+   phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
@@ -196,6 +197,7 @@ Short help:
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
    patterns      File Name Patterns
+   phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories
@@ -691,6 +693,7 @@ Test that default list of commands omits
    merge-tools   Merge Tools
    multirevs     Specifying Multiple Revisions
    patterns      File Name Patterns
+   phases        Working with Phases
    revisions     Specifying Single Revisions
    revsets       Specifying Revision Sets
    subrepos      Subrepositories