[Python-checkins] r75101 - in sandbox/trunk/dev: patches.rst setup.rst tools.rst why.rst
andrew.kuchling
python-checkins at python.org
Mon Sep 28 02:30:20 CEST 2009
Author: andrew.kuchling
Date: Mon Sep 28 02:30:20 2009
New Revision: 75101
Log:
Various edits
Modified:
sandbox/trunk/dev/patches.rst
sandbox/trunk/dev/setup.rst
sandbox/trunk/dev/tools.rst
sandbox/trunk/dev/why.rst
Modified: sandbox/trunk/dev/patches.rst
==============================================================================
--- sandbox/trunk/dev/patches.rst (original)
+++ sandbox/trunk/dev/patches.rst Mon Sep 28 02:30:20 2009
@@ -1,27 +1,27 @@
+.. _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>`_, and you will need to login
+ 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 the same way. When adding the
+* Submit documentation patches in the same way. When adding the
patch, be sure to set the "Category" field to
"Documentation".
-* We like unified diffs. We grudgingly accept contextual diffs.
- Straight ("ed-style") diffs are right out! If you don't know
- how to generate context diffs, you're probably not qualified to
- produce high-quality patches anyway <0.5 wink>.
-
+* 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.
@@ -32,21 +32,29 @@
* 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 way out of date.
+ release may be out of date.
* Please add a succinct message to your Roundup entry that
- explains what the patch is about that we can use directly as a checkin
+ 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
+* 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, there's no need to mail
- the documentation to a different address (in fact, in order to verify
- that the bundle is complete, it's easier to mail everything together).
-
-* There are a variety of additional `style requirements <style/>`_.
- Please have a look at these before writing new code. Also have a look at
- `PEP 8: Python Style Guide <http://www.python.org/dev/peps/pep-0008>`_.
+ (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>`_.
+
Modified: sandbox/trunk/dev/setup.rst
==============================================================================
--- sandbox/trunk/dev/setup.rst (original)
+++ sandbox/trunk/dev/setup.rst Mon Sep 28 02:30:20 2009
@@ -3,12 +3,12 @@
==================================================
-This document is meant to help get you the information needed to get the source
-code to Python, compile it for debugging purposes, set up your tools, and have
-a basic idea of the directory structure of the source code. For organizational
-purposes, details of the tools needed to work with the Python source code is
-kept in the `dev FAQ`_, so you will probably want to have it easily available as
-you read this document.
+This document is meant to help you set up your tools, get the source
+code to Python, compile it for debugging, and learn the basic
+directory structure of the source code. For organizational purposes,
+details of the tools needed to work with the Python source code are
+kept in the `dev FAQ`_, so you will probably want to have it easily
+available as you read this document.
.. contents::
Modified: sandbox/trunk/dev/tools.rst
==============================================================================
--- sandbox/trunk/dev/tools.rst (original)
+++ sandbox/trunk/dev/tools.rst Mon Sep 28 02:30:20 2009
@@ -16,12 +16,12 @@
svn co http://svn.python.org/projects/python/trunk python
-Running ``svn update`` will update the tree to the
-most recent version. Checkin messages and the accompanying diffs are
-sent to the `python-checkins <http://mail.python.org/mailman/listinfo/python-checkins>`_
-mailing list so that they get double-checked by the other developers.
-It's recommended that you subscribe to this list, especially if you've
-been granted write access to the source tree.
+Running ``svn update`` will update the tree to the most recent
+version. Checkin messages and the accompanying diffs are sent to the
+`python-checkins <http://mail.python.org/mailman/listinfo/python-checkins>`_ mailing
+list so that they can be read and double-checked by the other
+developers. If you've been granted write access to the source tree,
+it's strongly recommended that you subscribe to this list.
For information about SVN, see "Version Control with Subversion"
at http://svnbook.red-bean.com/.
@@ -30,12 +30,12 @@
```````````````````````````
-Write access to the Python SVN tree is not automatically granted,
-though there's no formal process to go through to get it. If the
-python-dev team knows who you are, whether through mailing list
+There's no formal process to gain write access to the Python SVN tree.
+If the python-dev team knows who you are, whether through mailing list
discussion, having submitted patches, or some other interaction, then
-you can ask for full SVN access. You'll need to have an SSH key, and
-provide it with your request.
+you may ask for full SVN access and have a reasonable chance of being
+accepted. You'll need to have an SSH key and include it with your
+request.
If you're granted SVN write access, you have to follow a few simple
rules.
@@ -43,8 +43,8 @@
* Use the patch manager to submit your first two or three patches for
review before you commit, unless specifically instructed otherwise.
-* Before making a code change, make sure you've checked out the most
- current version.
+* Before making a code change, always make sure you've checked out the
+ most current version.
* Before checking in a code change, re-run the entire Python test
suite to be sure that you haven't broken anything. To run the
@@ -53,17 +53,19 @@
./python ./Lib/test/testall.py
- If the module you're modifying doesn't have a test suite, you
- could consider writing a set of test cases for it.
-
* When fixing a bug, you should add a test case to the test suite
located in ``Lib/test/`` that would have caught this bug.
When adding a whole new class or module, you should add a set of
tests for it.
+ If the module you're modifying doesn't have a test suite, create
+ one, even if it only includes a single test that exercises the
+ change you're making. Consider writing a larger set of test cases
+ for the module.
+
* If a change affects OS-dependent behavior, run your tests on as
many OSes as you have easy access to. For additional testing, see the
- `Python Testers <http://www.python.org/moin/PythonTesters>`_ page.
+ `Python Testers <http://www.python.org/moin/PythonTesters>`_ page.
* When a patch changes behavior or fixes a noteworthy bug, you
should add an entry to the ``Misc/NEWS`` file about the
@@ -81,8 +83,8 @@
your fix is correct and doesn't introduce any incompatibilities.
* When in doubt, don't commit changes. If you're not sure a
- patch is bug-free, or are in doubt about the approach it takes, don't
- check in the patch and trust that it'll all get sorted out eventually.
+ patch is correct or are uncertain about the approach it takes, don't
+ apply the patch and trust that it'll all get sorted out eventually.
Instead, create a patch in the patch tracker (see below) and discuss
the patch with the other developers until everyone agrees it's
correct.
@@ -103,39 +105,30 @@
Bug Tracking
======================
-To report a bug in Python, use `the issue tracker <http://bugs.python.org>`_. Don't report bugs by posting them to a mailing list or
-by sending them to a particular developer as a private e-mail; most
-likely the bug will end up buried under subsequent postings and
-e-mails and subsequently forgotten. Once a problem is recorded in the
-bug tracker, though, it's unlikely to be lost. It may sit unchanged
-for a while until someone gets around to looking at it, but before
+To report a bug in Python, use `the issue tracker
+<http://bugs.python.org>`_. Don't report bugs by posting them to a
+mailing list or by sending them to a particular developer as a private
+e-mail; most likely the bug will end up buried under later postings
+and e-mails and subsequently forgotten. Once a problem is recorded in
+the bug tracker, though, it won't get lost. It may sit unchanged for
+a while until someone gets around to looking at it, but before
releases someone will go over the outstanding bugs and fix or close
-them. PEP 3, `"Guidelines for Handling Bug Reports" <http://www.python.org/dev/peps/pep-0003>`_ explains the procedures for handling bugs
-once they've been reported.
+them. PEP 3,
+`"Guidelines for Handling Bug Reports" <http://www.python.org/dev/peps/pep-0003>`_
+explains the procedures for handling bugs once they've been reported.
Patch Tracking
========================
Just like bugs, and for much the same reasons, patches should be
-submitted to the `issue tracker <http://bugs.python.org>`_, and not through e-mail. Often a patch will need some
-modification before final acceptance, so be prepared to go through a
+submitted to the `issue tracker <http://bugs.python.org>`_, and not posted
+to python-dev or e-mailed to people. Often a patch will need some
+modification before final acceptance, so be prepared for a
few iterations before the patch is ready to be checked in.
-Some conventions that should be followed when preparing a patch are:
-
-* Unified diffs are preferred (this is what Subversion and most other version control
- systems produce by default), so generate the patch using ``diff -u``.
-
-* 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 style in Guido's style guide,
- described in PEP 8, `"Style Guide for Python Code" <http://www.python.org/dev/peps/pep-0008>`_.
+For conventions that should be followed when preparing a patch,
+see the :ref:`patch-guidelines`.
URL Redirectors
@@ -150,10 +143,10 @@
http://bugs.python.org/1010
-From the times when the issues where tracked at SourceForge,
+From the time when the issues where tracked at SourceForge,
another redirector is available at
http://www.python.org/sf/1010
The old URLs using the SF redirector continue to work; URLs
-that point the sf.net directly are no longer valid.
+that point at sf.net directly are no longer valid.
Modified: sandbox/trunk/dev/why.rst
==============================================================================
--- sandbox/trunk/dev/why.rst (original)
+++ sandbox/trunk/dev/why.rst Mon Sep 28 02:30:20 2009
@@ -47,13 +47,13 @@
submitted patches. A newborn project will have to grow for some
time before it needs such tools, and many projects don't survive
that long. Working on a large project such as Python will show you
- how to use these tools effectively in order to work with the 60 or
- so other developers.
+ how to use these tools effectively in order to work with over 100
+ other developers.
* The most important skill Python can teach is the delicate
skill of working in a diverse group.
- There's a core group of around 60 developers. Roughly 10 of them
+ There's a core group of around 115 developers. Roughly 10 of them
are very active, making the majority of commits to the source tree,
and the rest make occasional commits and provide opinions and
advice. Many people outside this core group contribute
More information about the Python-checkins
mailing list