[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