.. _patch-guidelines:

==================================
Python Patch Submission Guidelines
==================================

We're using the Roundup bug/issue tracker to track patches.  Here are the main
guidelines:

* Submit your patch to the `issue tracker <http://bugs.python.org/>`_ interface.
  You will need to `register with Roundup
  <http://bugs.python.org/user?@template=register>`_.  You must login before
  submitting a patch, or else the 'Create New' link will not appear.

* Submit documentation patches in the same way.  When adding the patch, be sure
  to set the "Category" field to "Documentation".

* Unified diffs are preferred, so generate the patch using ``diff -u``.  This is
  what Subversion and most other version control systems produce by default.

* Please use forward diffs.  That is, use ``diff -u oldfile newfile``, and not
  the other way around.

* If you send diffs for multiple files, concatenate all the diffs in a single
  text file.  Please don't produce a zip file with multiple patches.

* We appreciate it if you send patches relative to the `current svn tree
  <http://www.python.org/dev/faq/#how-do-i-get-a-checkout-of-the-repository-read-only-and-read-write>`_.
  These are our latest sources.  Even a patch relative to the latest alpha or
  beta release may be out of date.

* Please add a succinct message to your Roundup entry that explains the purpose
  of the patch and can be used as a checkin message.  Ideally, such a message
  explains the problem and describes the fix in a few lines.

* For patches that add or change functionality: please also update the
  **documentation** and the **testcases** (the ``Lib/test`` subdirectory).  For
  new modules, we appreciate a new test module (typically test/test_spam.py).
  In this case, do not create a separate issue for the documentation or test
  cases; having everything in one issue makes it easier to verify that the
  bundle is complete.

* Patches to C code should follow Python's standard style, described in PEP 7,
  `"Style Guide for C Code" <http://www.python.org/dev/peps/pep-0007>`_.

  If you're using Emacs to edit your C code, cc-mode supports Python's standard
  style for old source files.  Run the ``c-set-style`` command and select the
  'python' style.  New source files use 4-space indents, not tabs.

* Code written in Python should follow the conventions described in PEP 8,
  `"Style Guide for Python Code" <http://www.python.org/dev/peps/pep-0008>`_.