[Python-checkins] devguide: Write a guide to committing a patch.

Tue Jan 18 07:14:51 CET 2011

Hi,

On Thu, Jan 13, 2011 at 12:44 AM, brett.cannon
<python-checkins at python.org>wrote:

> 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
>

s/current patch/current branch/

> +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::
>

Here you could mention that there are two ways to deal with files that have
conflicts (marked with 'C' by svn):
1) revert them with 'svn revert filename' and then change them manually;
2) edit the file directly to resolve the conflict and then use 'svn resolved
filename';
until there are no more files marked with 'C' in 'svn stat'.
It's also a good idea to cat svnmerge-commit-message.txt and double check
that the message is correct.

> +
> +    svn ci -F svnmerge-commit-message.txt
> +
> +This will commit the bacport along with using the commit message created
> by
>

s/bacport/backport/

> +``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.
>

Maybe a short paragraph about "svnmerge block" can be included here.

> +
> +
> +.. _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<http://www.chiark.greenend.org.uk/%7Esgtatham/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
> _______________________________________________
> Python-checkins mailing list
> Python-checkins at python.org
> http://mail.python.org/mailman/listinfo/python-checkins
>
>
Best Regards,
Ezio Melotti
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-checkins/attachments/20110118/2c6d3a02/attachment-0001.html>