[Python-Dev] draft of patch guidelines (original) (raw)

Brett Cannon brett at python.org
Thu Aug 24 21:22:42 CEST 2006

Below is a draft for a set of patch guidelines. This is meant for that times where people ask "how do a create a patch for a change I made" or where to point people if they created a patch but it comes up short (no tests, etc.). Hopefully this will go up on python.org/dev/ .

Let me know of any errors and such.

About /////

This set of guidelines is meant for people who have written code that they wish to have committed to the Python programming language. This means that this set of guidelines assumes you have already written code and thus just want to know the steps required to generate the patch necessary to submit your change for addition in Python. The assumption you are using a UNIX-style shell is also made.

If you need help with any of these steps, please ask for it! Usually you can create a new patch missing a few steps and the Python developers will try to help you complete it so that your patch can eventuallly be accepted.

Guidelines for committing code to Python will be contained in a separate document.

.. contents::

Steps to Creating a Patch /////////////////////////

Read the Developer Intro to understand the scope of your proposed change

Changes to Python come in various levels of scope. You could be fixing a simple bug in the standard library. You might be trying to add a new feature to a module. You might even be suggesting a new feature to the language. All three have a different amount of scope and thus require varying amounts of work to get approval.

Please read the Developer Intro_ doc to make sure you realize the proper scope of what you are doing. It also tells you the rough steps needed for varying types of changes to be accepted.

Add the appropriate unit tests

Python prides itself on being a very stable piece of software. We maintain this by having a regression test suite that contains a huge amount of unit tests that exercise both the language and the standard library.

Any change you make to Python requires a unit test. If your patch is to fix a bug, then a test exercising that bug and your fix is needed. If it is a new feature then an entirely new regression test might be needed. The important thing is that your new code is exercised within Python's test suite.

Add the proper document changes

If your patch will change or add new semantics, you must update the documentation. If your code clarifies some ambiguous behaviour, you must update the docs. The only time you do not need to touch the documentation is if your patch fixes a bug or adds new unit tests.

Make your code follow the style guidelines

PEP 7_ and PEP 8_ are the style guidelines for C and Python code, respectively. Your code must conform to the style guidelines before it is accepted.

Generate a patch

In general, people get their copy of the Python source from two locations: a svn checkout or from downloaded source. Both have slightly different steps in terms of generating patches.

Working from a svn checkout is the best way to create a patch. It makes it easier on the Python developers since there is less chance of any merge problems. It also raises the chances that a developer will be willing to put the time and effort into working with you and your patch. If you need help with working with svn and Python's repository, see the Developer FAQ_. Working from downloaded source is so inferior to working with a svn checkout that it will not be discussed here (although patches will be accepted against downloaded code).

First step is to update your svn checkout with svn update. Once you have done that and resolved the merge conflicts, generate a patch containing the files you have changed. You can see what files you have touched with svn status. If it lists only modified files you want to include in your patch, you can then generate your patch::

svn diff > PATCH_FILE

Make sure to name PATCH_FILE to a reasonable name and be prepared to upload it in a later step. Also, please note what revision number you are working against. This can be found by executing::

python -c "import sys; print sys.version"

Create a tracker item on SourceForge

First make sure you have a SourceForge account. Once you have one and havve logged in, go to the SF patch tracker for Python and create a new tracker item.

In the new tracker item, set the item's fields as so:

Reference the patch in proper bug reports

If your patch fixes a bug, add a follow-up to that bug report referencing the patch. If there is not bug report but your patch does fix a bug, then quickly create a bug report.

Wait for a developer to contact you

At this point you need to wait for a Python developer to come along and look at your patch. This might be a while as all Python developers are volunteers and thus have a limited amount of time. Do not be surprised if it takes weeks or more before your patch is examined.

There is a standing offer that if you review five other patches (by commenting on its correctness, helping it meet these guidelines, etc.), then a developer will definitely have a look at any patch you specify. Just email python-dev with what five patches you reviewed (and what you did for the review) and the patch you want examined.

.. _Developer Intro: http://www.python.org/dev/intro/ .. _PEP 7: http://www.python.org/dev/peps/pep-0007/ .. _PEP 8: http://www.python.org/dev/peps/pep-0008/ .. _Developer FAQ: http://www.python.org/dev/faq .. _SourceForge account: http://sourceforge.net/account/newuser_emailverify.php .. _SF patch tracker: http://sourceforge.net/tracker/?group_id=5470&atid=305470 -------------- next part -------------- An HTML attachment was scrubbed... URL: http://mail.python.org/pipermail/python-dev/attachments/20060824/85d3792f/attachment.htm

More information about the Python-Dev mailing list