[Python-checkins] devguide: Write a guide to committing a patch.
brett.cannon
python-checkins at python.org
Thu Jan 13 00:44:13 CET 2011
brett.cannon pushed 75300a08c6d7 to devguide:
http://hg.python.org/devguide/rev/75300a08c6d7
changeset: 88:75300a08c6d7
tag: tip
user: Brett Cannon <brett at python.org>
date: Wed Jan 12 15:44:04 2011 -0800
summary:
Write a guide to committing a patch.
files:
committing.rst
faq.rst
index.rst
diff --git a/committing.rst b/committing.rst
new file mode 100644
--- /dev/null
+++ b/committing.rst
@@ -0,0 +1,47 @@
+.. _committing:
+
+Committing Patches
+==================
+
+As a core developer you will occasionally want to commit a patch created by
+someone else. When doing so you will want to make sure of some things.
+
+First, make sure the patch in a good state. Both :ref:`patch` and :ref:`triage`
+explain what is to be expected of a patch. Typically patches that get passed by
+triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS``
+entries.
+
+Second, make sure the patch does not break backwards-compatibility without a
+good reason. This means :ref:`running the test suite <runtests>` to make sure
+everything still passes. It also means that if semantics do change there must
+be a good reason for the the breakage of code the change will cause (and it
+**will** break someone's code). If you are unsure if the breakage is worth it,
+ask on python-dev.
+
+Third, backport as necessary. If the patch is a bugfix and it does not break
+backwards-compatibility *at all*, then backport it to the branch(es) in
+maintenance mode. The easiest way to do this is to apply the patch in the
+development branch, commit, and then use svnmerge.py_ to backport the patch.
+
+For example, let us assume you just made commit 42 in the development branch
+and you want to backport it to the ``release31-maint`` branch. You would change
+your working directory to the maintenance branch and run the command::
+
+ svnmerge.py merge -r 42
+
+This will try to apply the patch to the current patch and generate a commit
+message. You will need to revert ``Misc/NEWS`` and do a new entry (the file
+changes too much between releases to ever have a merge succeed). Once your
+checkout is ready to be committed, do::
+
+ svn ci -F svnmerge-commit-message.txt
+
+This will commit the bacport along with using the commit message created by
+``svnmerge.py`` for you.
+
+If it turns out you do not have the time to do a backport, then at least leave
+the proper issue open on the tracker with a note specifying that the change
+should be backported so someone else can do it.
+
+
+.. _svnmerge.py: http://svn.apache.org/repos/asf/subversion/trunk/contrib/client-side/svnmerge/svnmerge.py
diff --git a/faq.rst b/faq.rst
--- a/faq.rst
+++ b/faq.rst
@@ -44,65 +44,6 @@
=========== ============================================================== ==========================================================================
-How do I prepare a new branch for merging?
-------------------------------------------
-
-You need to initialize a new branch by having ``svnmerge.py`` discover the
-revision number that the branch was created with. Do this with the command::
-
- svnmerge.py init
-
-Then check in the change to the root of the branch. This is a one-time
-operation (i.e. only when the branch is originally created, not when each
-developer creates a local checkout for the branch).
-
-
-How do I merge between branches?
---------------------------------
-
-In the current situation for Python there are four branches under development,
-meaning that there are three branches to merge into. Assuming a change is
-committed into ``trunk`` as revision 0001, you merge into the 2.x maintenance
-by doing::
-
- # In the 2.x maintenance branch checkout.
- svnmerge.py merge -r 0001
- svn commit -F svnmerge-commit-message.txt # r0002
-
-To pull into py3k::
-
- # In a py3k checkout.
- svnmerge.py merge -r 0001
- svn commit -F svnmerge-commit-message.txt # r0003
-
-The 3.x maintenance branch is a special case as you must pull from the py3k
-branch revision, *not* trunk::
-
- # In a 3.x maintenance checkout.
- svnmerge.py merge -r 0003 # Notice the rev is the one from py3k!
- svn resolved .
- svn commit -F svnmerge-commit-message.txt
-
-
-How do I block a specific revision from being merged into a branch?
--------------------------------------------------------------------
-
-With the revision number that you want to block handy and ``svnmerge.py``, go
-to your checkout of the branch where you want to block the revision and run::
-
- svnmerge.py block -r <revision #>
-
-This will modify the repository's top directory (which should be your current
-directory) and create ``svnmerge-commit-message.txt`` which contains a
-generated log message.
-
-If the command says "no available revisions to block", then it means someone
-already merged the revision.
-
-To check in the new metadata, run::
-
- svn ci -F svnmerge-commit-message.txt
-
SSH
=======
@@ -158,21 +99,6 @@
.. _Pageant: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
-Can I make check-ins from machines other than the one I generated the keys on?
-------------------------------------------------------------------------------
-
-Yes, all you need is to make sure that the machine you want to check
-in code from has both the public and private keys in the standard
-place that ssh will look for them (i.e. ~/.ssh on Unix machines).
-Please note that although the key file ending in .pub contains your
-user name and machine name in it, that information is not used by the
-verification process, therefore these key files can be moved to a
-different computer and used for verification. Please guard your keys
-and never share your private key with anyone. If you lose the media
-on which your keys are stored or the machine on which your keys are
-stored, be sure to report this to pydotorg at python.org at the same time
-that you change your keys.
-
Editors and Tools
diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -16,6 +16,7 @@
languishing
communication
coredev
+ committing
.. todolist::
@@ -48,7 +49,7 @@
* :ref:`languishing`
* :ref:`communication`
* :ref:`coredev`
- * `Committing patches <XXX>`_
+ * :ref:`committing`
Proposing changes to Python itself
--
Repository URL: http://hg.python.org/devguide
More information about the Python-checkins
mailing list