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

[Brett Cannon]

On Mon, Jan 17, 2011 at 22:14, Ezio Melotti <ezio.melotti at gmail.com> wrote:
> 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/

Fixed in a previous 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::
>
> 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.

Done.

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

Fixed in a previous commit.

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

No because I have not seen people bother with svnmerge block in a while.

-Brett

>
>>
>> +
>> +
>> +.. _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
>> _______________________________________________
>> Python-checkins mailing list
>> Python-checkins at python.org
>> http://mail.python.org/mailman/listinfo/python-checkins
>>
>
> Best Regards,
> Ezio Melotti
>
> _______________________________________________
> Python-checkins mailing list
> Python-checkins at python.org
> http://mail.python.org/mailman/listinfo/python-checkins
>
>