help: add phases topic

mercurial/help/phases.txt

@@ -0,0 +1,61 b''
+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.

mercurial/help.py

@@ -73,6 +73,7 b' 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

tests/test-globalopts.t

@@ -347,6 +347,7 b' 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 b' 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

tests/test-help.t

@@ -119,6 +119,7 b' 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 b' 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 b' 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