[Python-checkins] devguide: Move to using mq for basic usage.

brett.cannon python-checkins at python.org
Wed Feb 9 23:19:23 CET 2011


brett.cannon pushed 73e11f64a704 to devguide:

http://hg.python.org/devguide/rev/73e11f64a704
changeset:   286:73e11f64a704
branch:      hg_transition
tag:         tip
user:        Brett Cannon <brett at python.org>
date:        Wed Feb 09 14:19:16 2011 -0800
summary:
  Move to using mq for basic usage.

files:
  patch.rst

diff --git a/patch.rst b/patch.rst
--- a/patch.rst
+++ b/patch.rst
@@ -10,32 +10,55 @@
 Tool Usage
 ''''''''''
 
-.. _named-branch-workflow:
+.. _mq-workflow:
 
 Mercurial allows for various workflows according to each person's or
-project's preference.  We present here a very simple solution based on `named
-branches <http://mercurial.selenic.com/wiki/NamedBranches>`_ for
-non-committers.  Before you start modifying things in your working copy, type::
+project's preference.  We present here a very simple solution based on mq_
+(Mercurial Queue) non-core developers.
 
-   hg branch mywork
+If you have not done so previously, make sure that the extension has been
+turned on in your ``.hgrc`` or ``Mercurial.ini`` file::
+
+   [extensions]
+   mq =
+
+You can verify this is working properly by running ``hg help mq``.
+
+
+Before you start modifying things in your working copy, type::
+
+   hg qnew mywork
 
 where ``mywork`` is a descriptive name for what you are going to work on.
-Then all your local commits will be recorded on that branch, which is an
-effective way of distinguishing them from other (upstream) commits.
+This will create a patch in your patch queue. Whenever you have reached a point
+that you want to save what you have done, run::
 
-Make sure to do your branching from the ``default`` branch (type ``hg branch``
-to see which branch is active). To switch between branches, e.g., switch to the
-``default`` branch, do::
+   hg qrefresh
 
-   hg update default
+This will update the patch to contain all of the changes you have made up to
+this point. If you have any you have added or removed, use ``hg add`` or ``hg
+remove``, respectively, before running ``hg qrefresh``.
 
-When you are done with a branch, you can mark it as closed by doing the
-following while the branch you wish to close is active::
+When you are done with your work, you can create a patch to upload to the
+`issue tracker`_ with::
 
-   hg commit --close-branch
+   hg qdiff > patch.diff
 
-This deletes nothing, but it stops the branch from being listed as active in
-your checkout.
+When you are done with your changes, you can delete them with::
+
+   hg qdelete mywork
+
+For more advanced usage of mq, read the `mq chapter
+<http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html>`_
+of `Mercurial: The Definitive Guide <http://hgbook.red-bean.com/>`_.
+
+You can obviously use other workflows if you choose, just please make sure that
+the generated patch is *flat* instead of containing a diff for each changeset
+(e.g., if you have two or more changesets to a single file it should show up as
+a single change diff against the file instead of two separate ones).
+
+.. _issue tracker: http://bugs.python.org
+.. _mq: http://mercurial.selenic.com/wiki/MqExtension
 
 
 Preparation
@@ -93,34 +116,30 @@
     make patchcheck
 
 This will check and/or fix various common things people forget to do for
-patches, such as adding any new files needing for the patch to work.
+patches, such as adding any new files needing for the patch to work (do not
+that not all checks apply to non-core developers).
 
-The following instructions assume you are using the :ref:`named branch approach
-<named-branch-workflow>` suggested earlier.  To create your patch, first check
+The following instructions assume you are using the :ref:`mq approach
+<mq-workflow>` suggested earlier.  To create your patch, first check
 that all your local changes have been committed, then type the following::
 
-   hg diff -r default > mywork.patch
+   hg qdiff > mywork.patch
 
 To apply a patch generated this way, do::
 
-    patch -p1 < mywork.patch
+    hg qimport mywork.patch
 
-To undo a patch applied in your working copy, simply can revert **all** changes::
+This will create a patch in your queue with a name that matches the filename.
+You can use the ``-n`` argument to specify a different name.
 
-    hg revert --all
+To undo a patch imported into your working copy, simply delete the patch from
+your patch queue::
 
-This will leave backups of the files with your changes still intact. To skip
-that step, you can use the ``--no-backup`` flag.
+    hg qdelete mywork.patch
 
 Please refer to the :ref:`FAQ <faq>` for :ref:`more information
 <hg-local-workflow>` on how to manage your local changes.
 
-.. note:: The ``patch`` program is not available by default under Windows.
-   You can find it `here <http://gnuwin32.sourceforge.net/packages/patch.htm>`_,
-   courtesy of the `GnuWin32 <http://gnuwin32.sourceforge.net/>`_ project.
-   Also, you may find it necessary to add the "``--binary``" option when trying
-   to apply Unix-generated patches under Windows.
-
 
 Submitting
 ----------

--
Repository URL: http://hg.python.org/devguide


More information about the Python-checkins mailing list