[Python-Dev] draft of patch guidelines

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:

* Private
    Leave unchecked.
* Category
    Set to what area of Python your patch affects.
* Group
    Set to the version of Python that the patch was generated against.
* Assigned To
    Leave as-is.
* Priority:
    Leave as-is.
* Summary
    Briefly describe what the patch does.
* Detailed Description
    Describe in more detail what the patch does.  Make sure to mention
    the revision number the patch is against here.  Also mention any
    bugs that the patch fixes.
* Upload and Attach a File
    Point to the patch you generated.
* File Description
    Mention it is the initial version of the patch.  If you end up
    uploading newer versions of your patch you then specify how it is
    different from the previous one.


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