[Python-checkins] r75044 - in sandbox/trunk/dev: contributing.rst culture.rst faq.rst index.rst patches.rst process.rst setup.rst tools.rst why.rst workflow.rst
andrew.kuchling
python-checkins at python.org
Thu Sep 24 13:43:13 CEST 2009
Author: andrew.kuchling
Date: Thu Sep 24 13:43:13 2009
New Revision: 75044
Log:
Initial commit of dev. guide
Added:
sandbox/trunk/dev/
sandbox/trunk/dev/contributing.rst
sandbox/trunk/dev/culture.rst
sandbox/trunk/dev/faq.rst
sandbox/trunk/dev/index.rst
sandbox/trunk/dev/patches.rst
sandbox/trunk/dev/process.rst
sandbox/trunk/dev/setup.rst
sandbox/trunk/dev/tools.rst
sandbox/trunk/dev/why.rst
sandbox/trunk/dev/workflow.rst
Added: sandbox/trunk/dev/contributing.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/contributing.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,134 @@
+
+==============================
+How You Can Contribute
+==============================
+
+
+There are various ways one can contribute to Python and they do not all involve
+knowing the internals of Python. Nor do they necessarily require writing
+code! All it takes to contribute is a willing to learn and some free time.
+
+This document assumes you have already read how to get `set up`_ and how the
+`issue workflow`_ works.
+
+.. _set up: /dev/setup/
+.. _issue workflow: /dev/workflow/
+
+
+Helping with the Documentation
+==============================
+
+There is almost always something to help out with in terms of Python's
+documentation_. If you have ever found something that was not completely clear
+or wished there was an example to go along with some complex idea then you have
+found something that could use improvement. Simply submit an issue with a patch
+to fix the problem you had.
+
+If you want to help with a known issue with the documentation then look at the
+`open documentation bugs
+<http://bugs.python.org/issue?%40search_text=&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&components=4&versions=&dependencies=&assignee=&keywords=&priority=&%40columns=priority&%40group=priority&status=1&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40queryname=&%40old-queryname=&%40action=search>`_.
+You can comment on documentation issues that have patches or write a patch to
+fix an issue. See the `documentation guide
+<http://docs.python.org/dev/documenting/index.html>`_ on how Python's
+documentation is written.
+
+.. _documentation: http://docs.python.org/dev/
+
+
+Writing Unit Tests
+==================
+
+Python is far from having good coverage (roughly 90% and better) for all of its
+code. It is always helpful to increase the coverage by writing more unit tests
+to help raise the code coverage. An easy way to see what kind of coverage
+exists for code is to look `here <http://coverage.livinglogic.de/>`_.
+
+Please realize, though, that your patch may not be reviewed immediately! Since
+Python is run entirely by open source developers who volunteer their time they
+only have so many hours a week to look at issues in the tracker. It might be
+quite some time until someone manages to free up enough time to get to your
+patch. But do know that your help is still appreciated no matter how long we
+take to get to your work!
+
+
+Fixing Bugs
+===========
+
+If you simply look at the `open bugs
+<http://bugs.python.org/issue?status=-1,1,3&@sort=-activity&@search_text=&@dispname=Show%20All&@startwith=0&@filter=status&@group=priority&@columns=id,activity,title,creator,assignee,status,type&@pagesize=50>`_
+on the `issue tracker`_ you will notice help is always needed. By writing a
+solid patch for a bug you make it so that the core developers do not have to
+spend what little time they have fixing a bug but instead doing patch reviews
+which are almost always a better use of time. Just make sure to follow what is
+outlined in the `issue workflow`_ for what is required of a good patch.
+
+And you do not need to know C or how Python's intepreter works to contribute!
+Simply restrict your search in the issue tracker to only a specific *component*
+that requires only a certain skill set. For instance,
+if you are looking for an explicitly `easy issue
+<http://bugs.python.org/issue?%40search_text=&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&%40columns=type&components=&%40columns=components&versions=&dependencies=&assignee=&%40columns=assignee&keywords=6&priority=&%40group=priority&status=1&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40queryname=&%40old-queryname=&%40action=search>`_ that should take no more
+than a day (about the length of a bug day) to work on they are
+flagged in the issue tracker as such. If you are comfortable with working in
+Python code you can look at issues pertaining to `Lib
+<http://bugs.python.org/issue?%40search_text=&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&%40columns=type&components=9&versions=&dependencies=&assignee=&%40columns=assignee&keywords=&priority=&%40group=priority&status=1&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40queryname=&%40old-queryname=&%40action=search>`_
+or other components that are inherently only Python code. If you are
+comfortable with `extension modules
+<http://bugs.python.org/issue?%40search_text=&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&%40columns=type&components=5&versions=&dependencies=&assignee=&%40columns=assignee&keywords=&priority=&%40group=priority&status=1&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40queryname=&%40old-queryname=&%40action=search>`_
+you can find issues pertaining to those.
+And when you are ready to learn the internal details of Python you can tackle
+issues related to the `interpreter core
+<http://bugs.python.org/issue?%40search_text=&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&%40columns=type&components=8&versions=&dependencies=&assignee=&%40columns=assignee&keywords=&priority=&%40group=priority&status=1&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40queryname=&%40old-queryname=&%40action=search>`_.
+There are other components you can narrow your search on as well if you so
+choose. Just play around with the search feature of the issue tracker to find a
+list of issues you might be interested at looking into.
+
+Please realize that while your patch is greatly appreciated, it may be some
+time before a core developer gets around to looking at your patch. It is simply
+an issue of someone having the free time and expertise to look at your work in
+order to review it and commit it.
+
+
+Triaging Issues
+===============
+
+While Python is a very solid piece of software, bugs are found. Plus people are
+always suggesting new features through patches, improving existing code, etc.
+This leads to a lost of issues being created in the `issue tracker`_. Help is
+always appreciated to go through issues and perform triage by following what is
+discussed in the `issue workflow`_. This ranges from helping validate a bug
+exists in Python's in-development version to reviewing patches.
+
+If you have helped out in the issue tracker for a little while or have been a
+good participant on python-dev you may ask for Developer privileges on the
+tracker which allow you to change any and all metadata on an issue.
+Please don't be shy about asking for the privilege! We are more liberal with
+giving out this ability than with commit privileges so don't feel like you have
+to have been contributing for a year to gain this ability. And with Developer
+privileges you can work more autonomously and be an even greater help by
+narrowing down what issues on the tracker deserve the most attention at any one
+time.
+
+.. _issue tracker: http://bugs.python.org/
+
+
+Become a Core Developer
+=======================
+
+To become a core developer and gain commit privileges for Python you typically
+need to have been an active developer on Python through the issue tracker and
+shown the ability to develop top-quality patches that require little or no
+input or changes from a core developer. Typically people take about a year to
+reach this level; some people get there faster, others longer. It can
+be short-circuited, though, if a core developer is willing to shepherd you
+through the process, but this is typically reserved for special situations like
+`GSoC/GHOP <http://socghop.appspot.com/>`_. Essentially if a core developer is
+willing to vouch for you and initially take personal responsibility for your
+actions as a developer you can gain commit privileges that way.
+
+When you think you have been submitting patches regularly that have not required
+much feedback from a core developer you can email python-dev requesting commit
+privileges. If it is decided you are ready then you mail your SSH 2 key (see
+the `dev FAQ`_ on how to do this) to python-dev and you will receive your
+commit privileges.
+
+.. _dev FAQ: /dev/faq/
Added: sandbox/trunk/dev/culture.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/culture.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,70 @@
+====================
+Python Culture
+====================
+
+Each software project has its own culture and style, its own
+approach to solving problems. Python has its own distinctive style,
+of course, and if you're a Python user, that style has probably rubbed
+off on you to some extent. Python tries to keep things simple, to be
+orthogonal but not too much so, and to assist the programmer as much
+as possible.
+
+The first and most important thing is to be friendly, even (I
+should say *especially*) with people who disagree with you.
+Other people are not idiots just because they disagree with you, so
+don't call them idiots. Rudeness and flaming, especially on
+python-dev, is a fast way to get ignored. Have a sense of humour, and
+don't take things too seriously.
+
+Another useful skill is to know when to give up. If a thread has
+gone on for dozens or hundreds of posts with no clear consensus
+emerging, one of two things will happen. Either Guido will make a
+BDFL pronouncement, which consists of him saying "We'll do it this
+way", or he's given up on the thread and isn't reading it at all any
+more. In either case, there's little point in continuing the
+discussion.
+
+Design Principles
+=================
+
+
+In June 1999, Tim Peters channeled Guido and listed 19 guiding
+principles for Python's design in a `comp.lang.python <news:comp.lang.python>`_ posting. The
+principles shouldn't be taken too seriously, as they're not
+hard-and-fast constraints and for each rule you can probably list
+instances where it's been broken. Still, no one has had much
+disagreement with this list of design criteria.
+
+* Beautiful is better than ugly.
+* Explicit is better than implicit.
+* Simple is better than complex.
+* Complex is better than complicated.
+* Flat is better than nested.
+* Sparse is better than dense.
+* Readability counts.
+* Special cases aren't special enough to break the rules.
+* Although practicality beats purity.
+* Errors should never pass silently.
+* Unless explicitly silenced.
+* In the face of ambiguity, refuse the temptation to guess.
+* There should be one -- and preferably only one -- obvious way to do it.
+* Although that way may not be obvious at first unless you're Dutch.
+* Now is better than never.
+* Although never is often better than *right* now.
+* If the implementation is hard to explain, it's a bad idea.
+* If the implementation is easy to explain, it may be a good idea.
+* Namespaces are one honking great idea -- let's do more of those!
+
+Don't take these 19 aphorisms too seriously -- tattooing them on your
+body is probably a bad idea, for example -- but it's instructive to
+contemplate them. Some parallels can be drawn to the guiding
+principles of extreme programming, most notably the emphasis on "Do
+the simplest thing that can possibly work".
+
+Another principle is "Correctness and clarity before speed." Most
+of the code in the Python interpreter and standard library is written
+in a very straightforward style. The developers aren't interested in
+making the interpreter run faster at the expense of unreadable or
+hard-to-follow tricky code. In the past working patches have been
+rejected because they would have made the code too difficult to
+maintain.
Added: sandbox/trunk/dev/faq.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/faq.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,1021 @@
+
+:Title: Frequently Asked Questions for Python Developers
+:Date: $Date: 2009年07月23日 06:21:27 -0400 (2009年7月23日) $
+:Version: $Revision: 10931 $
+:Web site: http://www.python.org/dev/faq/
+
+.. contents:: :depth: 3
+.. sectnum::
+
+General Information
+=====================================================================
+
+Where do I start?
+-----------------
+
+There are various links of the `dev page`_ to documents to help get you
+started.
+
+.. _dev page: /dev/
+
+
+How can I become a developer?
+---------------------------------------------------------------------------
+
+One way to become a developer is through the
+`School of Hard Knocks <http://mail.python.org/pipermail/python-dev/2002-September/028725.html>`_.
+
+Otherwise just contribute on a regular basis through patches and just ask for
+commit privileges once you have helped out enough that other developers tire of
+doing commits for you.
+
+
+Version Control
+==================================
+
+Where can I learn about the version control system used, Subversion (svn)?
+-------------------------------------------------------------------------------
+
+`Subversion`_ has its official web site at http://subversion.tigris.org/ (it
+is also known as ``svn`` thanks to that being the name of the executable of
+Subversion itself). A book on Subversion published by `O'Reilly Media`_,
+`Version Control with Subversion`_, is available for free online.
+
+With Subversion installed, you can run the help tool that comes with
+Subversion to get help::
+
+ svn help
+
+This will give you the needed information to use the tool. The man page for
+``svn`` is rather scant and thus not worth reading.
+
+.. _Subversion: http://subversion.tigris.org/
+.. _O'Reilly Media: http://www.oreilly.com/
+.. _Version Control with Subversion: http://svnbook.red-bean.com/
+
+
+What do I need to use Subversion?
+-------------------------------------------------------------------------------
+
+.. _download Subversion: http://subversion.tigris.org/getting.html
+
+UNIX
+'''''''''''''''''''
+
+First, you need to `download Subversion`_. Most UNIX-based operating systems
+have binary packages available for Subversion. Also, most package systems also
+have Subversion available.
+
+If you have checkin rights, you need OpenSSH_. This is needed to verify
+your identity when performing commits.
+
+.. _OpenSSH: http://www.openssh.org/
+
+Windows
+'''''''''''''''''''
+
+You have several options on Windows. One is to `download Subversion`_ itself
+which will give you a command-line version. Another option is to `download
+TortoiseSVN`_ which integrates with Windows Explorer.
+
+If you have checkin rights, you will also need an SSH client.
+`Download PuTTY and friends`_ (PuTTYgen, Pageant, and Plink) for this. All
+other questions in this FAQ will assume you are using these tools.
+
+Once you have both Subversion and PuTTY installed you must tell Subversion
+where to find an SSH client. Do this by editing
+``%APPDATA%\Subversion\config`` (on Win9x, this might be
+``c:\windows\Application Data\Subversionconfig``) to have the following
+section::
+
+ [tunnels]
+ ssh="c:/path/to/putty/plink.exe" -T
+
+Obviously change the path to be the proper one for your system. The ``-T``
+option prevents a pseudo-terminal from being created.
+
+You can use Pageant to prevent from having to type in your password for your
+SSH 2 key constantly. If you prefer not to have another program running,
+you need to create a profile in PuTTY.
+
+Go to Session:Saved Sessions and create a new profile named
+``svn.python.org``. In Session:Host Name, enter ``svn.python.org``. In
+SSH/Auth:Private key file select your private key. In Connection:Auto-login
+username enter ``pythondev``.
+
+With this set up, paths are slightly different than most other settings in that
+the username is not required. Do take notice of this when choosing to check
+out a project!
+
+.. _download TortoiseSVN: http://tortoisesvn.tigris.org/download.html
+.. _PuTTY: http://www.chiark.greenend.org.uk/~sgtatham/putty/
+.. _download PuTTY and friends: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
+
+
+How do I get a checkout of the repository (read-only and read-write)?
+-------------------------------------------------------------------------------
+
+Regardless of whether you are checking out a read-only or read-write version of
+the repository, the basic command is the same::
+
+ svn checkout <URL> [PATH]
+
+``<URL>`` is the specified location of the project within the repository that
+you would like to check out (those paths are discussed later). The optional
+``[PATH]`` argument specifies the local directory to put the checkout into. If
+left out then the tail part of ``<URL>`` is used for the directory name.
+
+For a read-only checkout, the format of ``<URL>`` is::
+
+ http://svn.python.org/projects/<path>
+
+with `<path>` representing the path to the project. A list of projects can be
+viewed at http://svn.python.org/view/ . Do note that any subdirectory may also
+be checked out individually.
+
+For a read-write checkout (with a caveat for Windows users using PuTTY without
+Pageant), the format for ``<URL>`` is::
+
+ svn+ssh://pythondev@svn.python.org/<path>
+
+There are three critical differences between a read-only URL and a read-write
+URL. One is the protocol being specified as ``svn+ssh`` and not ``http``.
+Next, notice the addition of the username ``pythondev`` (*note* that for
+Windows users using PuTTY without Pageant should leave off ``pythondev@`` if
+PuTTY was set up following the instructions in this FAQ). Lastly, note that
+``projects`` was removed from the path entirely for a read-write checkout.
+
+The repositories most people will be interested in are:
+
+=========== ============================================================== ==========================================================================
+Repository read-only read-write
+----------- -------------------------------------------------------------- --------------------------------------------------------------------------
+PEPs http://svn.python.org/projects/peps/trunk svn+ssh://pythondev@svn.python.org/peps/trunk
+2.6 http://svn.python.org/projects/python/branches/release26-maint svn+ssh://pythondev@svn.python.org/python/branches/release26-maint
+2.7 (trunk) http://svn.python.org/projects/python/trunk svn+ssh://pythondev@svn.python.org/python/trunk
+3.1 http://svn.python.org/projects/python/branches/release31-maint svn+ssh://pythondev@svn.python.org/python/branches/release31-maint
+3.2 http://svn.python.org/projects/python/branches/py3k svn+ssh://pythondev@svn.python.org/python/branches/py3k
+=========== ============================================================== ==========================================================================
+
+
+How do I update my working copy to be in sync with the repository?
+-------------------------------------------------------------------------------
+
+Run::
+
+ svn update
+
+from the directory you wish to update (and all subdirectories).
+
+
+How do I browse the source code through a web browser?
+-------------------------------------------------------------------------------
+
+Visit http://svn.python.org/view/ to browse the Subversion repository.
+
+
+Where can I find a downloadable snapshot of the source code?
+-------------------------------------------------------------------------------
+
+Visit http://svn.python.org/snapshots/ to download a tarball containing a daily
+snapshot of the repository.
+
+
+Who has commit privileges on the Subversion repository?
+-------------------------------------------------------------------------------
+
+See http://www.python.org/dev/committers for a list of committers.
+
+
+How do I get commit privileges on the svn repository if I had the same privileges on the CVS repository?
+---------------------------------------------------------------------------------------------------------
+
+If you have established commit privileges as listed at
+http://sourceforge.net/project/memberlist.php?group_id=5470 but do not have
+them yet for the Subversion repository, then there are a few steps you must
+take:
+
+#. Generate an SSH 2 public key
+#. Email key and name (first and last required, middle optional)
+#. Wait for verification email that the key has been installed
+#. Verify access
+
+
+How do I verify that my commit privileges are working?
+-------------------------------------------------------------------------------
+
+UNIX
+'''''''''''''''''''
+
+If you are listed as a committer at http://www.python.org/dev/committers , then
+you should be able to execute::
+
+ ssh pythondev at svn.python.org
+
+and have the following print out to your terminal::
+
+ ( success ( 1 2 ( ANONYMOUS EXTERNAL ) ( edit-pipeline ) ) )
+
+If something else is printed, then there is a problem with your SSH 2 public
+key and you should contact pydotorg at python.org .
+
+Windows
+'''''''''''''''''''
+
+If you are using Pageant, you can verify that your SSH 2 key is set up properly
+by running::
+
+ c:\path\to\putty\plink.exe pythondev at svn.python.org
+
+Using the proper path to your PuTTY installation, you should get a response
+from the server that says::
+
+ ( success ( 1 2 ( ANONYMOUS EXTERNAL ) ( edit-pipeline ) ) )
+
+If there is a failure, run ``plink`` with ``-v`` to analyse the problem.
+
+If you are using a profile in PuTTY, the best way to test is to try to log in
+through Open.
+
+
+What configuration settings should I use?
+-------------------------------------------------------------------------------
+
+Make sure the following settings are in your Subversion config file
+(``~/.subversion/config`` under UNIX)::
+
+ [miscellany]
+ enable-auto-props = yes
+
+ [auto-props]
+ * = svn:eol-style=native
+ *.c = svn:keywords=Id
+ *.h = svn:keywords=Id
+ *.py = svn:keywords=Id
+ *.txt = svn:keywords=Author Date Id Revision
+
+The ``[auto-props]`` line specifies the beginning of the section in the config
+file. The ``svn:eol-style`` setting tells Subversion to check out files using
+the native line endings on your OS. It will also automatically convert line
+endings upon committal so that they are consistent across all platforms. The
+``svn:keywords`` settings are to automatically substitute ``$keyword$``
+arguments in files that match the pattern. ``*.txt`` has more options so as to
+cover all needed keywords for PEPs_.
+
+The ``[miscellany]`` section and its one option make Subversion apply the
+various rules in the ``[auto-props]`` section automatically to all added or
+imported files into the respository.
+
+.. _PEPs: http://www.python.org/dev/peps/
+
+
+How do I add a file or directory to the repository?
+-------------------------------------------------------------------------------
+
+Simply specify the path to the file or directory to add and run::
+
+ svn add PATH
+
+Subversion will skip any directories it already knows about. But if
+you want new files that exist in any directories specified in ``PATH``, specify
+``--force`` and Subversion will check *all* directories for new files.
+
+You will then need to run ``svn commit`` (as discussed in
+`How do I commit a change to a file?`_) to commit the file to the repository.
+
+
+How do I commit a change to a file?
+-------------------------------------------------------------------------------
+
+To have any changes to a file (which include adding a new file or deleting an
+existing one), you use the command::
+
+ svn commit [PATH]
+
+Although ``[PATH]`` is optional, if PATH is omitted all changes
+in your local copy will be committed to the repository.
+**DO NOT USE THIS!!!** You should specify the specific files
+to be committed unless you are *absolutely* positive that
+*all outstanding modifications* are meant to go in this commit.
+
+To abort a commit that you are in the middle of, perform a commit with no
+message (i.e., close the text editor without adding any text for the message).
+Subversion will ask if you want to abort the commit or not at that point.
+
+If you do not like the default text editor Subversion uses for
+entering commmit messages, you may specify a different editor
+in your Subversion config file with the
+``editor-cmd`` option in the ``[helpers]`` section.
+
+
+How do I delete a file or directory in the repository?
+-------------------------------------------------------------------------------
+
+Specify the path to be removed with::
+
+ svn delete PATH
+
+Any modified files or files that are not checked in will not be deleted
+in the working copy on your machine.
+
+
+What files are modified locally in my working copy?
+-------------------------------------------------------------------------------
+
+Running::
+
+ svn status [PATH]
+
+will list any differences between your working copy and the repository. Some
+key indicators that can appear in the first column of output are:
+
+= ===========================
+A Scheduled to be added
+
+D Scheduled to be deleted
+
+M Modified locally
+
+? Not under version control
+= ===========================
+
+
+How do I find out what Subversions properties are set for a file or directory?
+-------------------------------------------------------------------------------
+
+::
+
+ svn proplist PATH
+
+
+How do I revert a file I have modified back to the version in the respository?
+-------------------------------------------------------------------------------
+
+Running::
+
+ svn revert PATH
+
+will change ``PATH`` to match the version in the repository, throwing away any
+changes you made locally. If you run::
+
+ svn revert -R .
+
+from the root of your local repository it will recursively restore everything
+to match up with the main server.
+
+
+How do I find out who edited or what revision changed a line last?
+-------------------------------------------------------------------------------
+
+You want::
+
+ svn blame PATH
+
+This will output to stdout every line of the file along with what revision
+number last touched that line and who committed that revision. Since it is
+printed to stdout, you probably want to pipe the output to a pager::
+
+ svn blame PATH | less
+
+
+How can I see a list of log messages for a file or specific revision?
+---------------------------------------------------------------------
+
+To see the log messages for a specific file, run::
+
+ svn log PATH
+
+That will list all messages that pertain to the file specified in ``PATH``.
+
+If you want to view the log message for a specific revision, run::
+
+ svn log --verbose -r REV
+
+With ``REV`` substituted with the revision number. The ``--verbose`` flag
+should be used to get a listing of all files modified in that revision.
+
+
+How can I edit the log message of a committed revision?
+-------------------------------------------------------------------------------
+
+Use::
+
+ svn propedit -r <revision> --revprop svn:log
+
+Replace ``<revision>`` with the revision number of the commit whose log message
+you wish to change.
+
+
+How do I get a diff between the repository and my working copy for a file?
+-------------------------------------------------------------------------------
+
+The diff between your working copy and what is in the repository can be had
+with::
+
+ svn diff PATH
+
+This will work off the current revision in the repository. To diff your
+working copy with a specific revision, do::
+
+ svn diff -r REV PATH
+
+Finally, to generate a diff between two specific revisions, use::
+
+ svn diff -r REV1:REV2 PATH
+
+Notice the ``:`` between ``REV1`` and ``REV2``.
+
+
+How do I undo the changes made in a recent committal?
+-------------------------------------------------------------------------------
+
+Assuming your bad revision is ``NEW`` and ``OLD`` is the equivalent of ``NEW
+- 1``, then run::
+
+ svn merge -r NEW:OLD PATH
+
+This will revert *all* files back to their state in revision ``OLD``.
+The reason that ``OLD`` is just ``NEW - 1`` is you do not want files to be
+accidentally reverted to a state older than your changes, just to the point
+prior.
+
+Note: PATH here refers to the top of the checked out repository,
+not the full pathname to a file. PATH can refer to a different
+branch when merging from the head, but it must still be the top
+and not an individual file or subdirectory.
+
+
+How do I update to a specific release tag?
+-------------------------------------------------------------------------------
+
+Run::
+
+ svn list svn+ssh://pythondev@svn.python.org/python/tags
+
+or visit::
+
+ http://svn.python.org/view/python/tags/
+
+to get a list of tags. To switch your current sandbox to a specific tag,
+run::
+
+ svn switch svn+ssh://pythondev@svn.python.org/python/tags/r242
+
+To just update to the revision corresponding to that tag without changing
+the metadata for the repository, note the revision number corresponding to
+the tag of interest and update to it, e.g.::
+
+ svn update -r 39619
+
+What you probably want though, is the switch that sandbox to the tag's url::
+
+ svn switch svn+ssh://pythondev@svn.python.org/python/tags/r242
+
+
+Why should I use ``svn switch``?
+-------------------------------------------------------------------------------
+
+You might find this small treatise by Giovanni Bajo in python-dev on the
+``svn switch`` command helpful:
+
+If you realize that each file/directory in Subversion is uniquely identified
+by a 2-space coordinate system [URL, revision] (given a checkout, you can
+use "svn info" to get its coordinates), then we can say that "svn up -r N"
+(for some revision number N) keeps the url unchanged and changes the
+revision to whatever number you specified. In other words, you get the
+state of the working copy URL at the time revision N was created. For
+instance, if you execute it with revision 39619 within the trunk working
+copy, you will get the trunk at the moment 2.4.2 was released.
+
+On the other hand, "svn switch" moves the URL: it basically "moves" your
+checkout from [old_URL, revision] to [new_URL, HEAD], downloading the
+minimal set of diffs to do so. If the new_URL is a tag URL
+(e.g. .../tags/r242), it means any revision is good, since nobody is going
+to commit into that directory (it will stay unchanged forever). So
+[/tags/r242, HEAD] is the same as any other [/tags/r242, revision] (assuming
+of course that /tags/r242 was already created at the time the revision was
+created).
+
+If you want to create a sandbox corresponding to a particular release tag,
+use svn switch to switch to [/tags/some_tag, HEAD] if you don't plan on
+doing modifications. On the other hand if you want to make modifications to
+a particular release branch, use svn switch to change to
+[/branches/some_branch, HEAD].
+
+
+How do I create a branch?
+-------------------------
+
+The best way is to do a server-side copy by specifying the URL for the source
+of the branch, and the eventual destination URL for the new branch::
+
+ svn copy SRC_URL DEST_URL
+
+You can then checkout your branch as normal. You will want to prepare your
+branch for future merging from the source branch so as to keep them in sync.
+To find out how to do that, read `How do I merge between branches?`_.
+
+
+What tools do I need to merge between branches?
+-----------------------------------------------
+
+You need `svnmerge.py
+<http://svn.collab.net/repos/svn/trunk/contrib/client-side/svnmerge/svnmerge.py>`__.
+
+
+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.
+
+
+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
+
+
+How do I include an external svn repository (external definition) in the repository?
+------------------------------------------------------------------------------------
+
+Before attempting to include an external svn repository into Python's
+repository, it is important to realize that you can only include directories,
+not individual files.
+
+To include a directory of an external definition (external svn repository) as a
+directory you need to edit the ``svn:externals`` property on the root of the
+repository you are working with using the format of::
+
+ local_directory remote_repositories_http_address
+
+For instance, to include Python's sandbox repository in the 'sandbox' directory
+of your repository, run ``svn propedit svn:externals .`` while in the root of
+your repository and enter::
+
+ sandbox http://svn.python.org/projects/sandbox/trunk/
+
+in your text editor. The next time you run ``svn update`` it will pull in the
+external definition.
+
+
+How can I create a directory in the sandbox?
+------------------------------------------------------------------------------
+
+Assuming you have commit privileges and you do not already have a complete
+checkout of the sandbox itself, the easiest way is to use svn's ``mkdir``
+command::
+
+ svn mkdir svn+ssh://pythondev@svn.python.org/sandbox/trunk/<directory>
+
+That command will create the new directory on the server. To gain access to
+the new directory you then checkout it out (substitute ``mkdir`` in the command
+above with ``checkout``).
+
+If you already have a complete checkout of the sandbox then you can just use
+``svn mkdir`` on a local directory name and check in the new directory itself.
+
+
+SSH
+=======
+
+How do I generate an SSH 2 public key?
+-------------------------------------------------------------------------------
+
+All generated SSH keys should be sent to pydotorg for adding to the list of
+keys.
+
+UNIX
+'''''''''''''''''''
+
+Run::
+
+ ssh-keygen -t rsa
+
+This will generate a two files; your public key and your private key. Your
+public key is the file ending in ``.pub``.
+
+Windows
+'''''''''''''''''''
+
+Use PuTTYgen to generate your public key. Choose the "SSH2 DSA" radio button,
+have it create an OpenSSH formatted key, choose a password, and save the private
+key to a file. Copy the section with the public key (using Alt-P) to a file;
+that file now has your public key.
+
+Is there a way to prevent from having to enter my password for my SSH 2 public key constantly?
+------------------------------------------------------------------------------------------------
+
+UNIX
+'''''''''''''''''''
+
+Use ``ssh-agent`` and ``ssh-add`` to register your private key with SSH for
+your current session. The simplest solution, though, is to use KeyChain_,
+which is a shell script that will handle ``ssh-agent`` and ``ssh-add`` for you
+once per login instead of per session.
+
+.. _KeyChain: http://www.gentoo.org/proj/en/keychain/
+
+Windows
+'''''''''''''''''''
+
+Running Pageant will prevent you from having to type your password constantly.
+If you add a shortcut to Pageant to your Autostart group and edit the shortcut
+so that the command line includes an argument to your private key then Pageant
+will load the key every time you log in.
+
+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.
+
+
+Compilation
+=====================================================================
+
+How do I create a debug build of Python?
+-----------------------------------------
+
+A debug build, sometimes called a "pydebug" build, has extra checks and bits of
+information to help with developing Python.
+
+UNIX
+'''''''''''''''''''''''
+
+The basic steps for building Python for development is to configuring it and
+then compile it.
+
+Configuration is typically::
+
+ ./configure --prefix=/dev/null --with-pydebug
+
+More flags are available to ``configure``, but this is the minimum you should
+do. This will give you a debug version of Python along with a safety measure
+to prevent you from accidentally installing your development version over
+your system install. If you are developing on OS X for Python 2.x and will not
+be working with the OS X-specific modules from the standard library, then
+consider using the ``--without-toolbox-glue`` flag to faster compilation time.
+
+Once ``configure`` is done, you then need to compile Python.::
+
+ make -s
+
+This will build Python with only warnings and errors being printed to
+stderr. If you running on a multi-core machine you can use the ``-j`` flag
+along with the number of cores your machine has to build Python faster
+(e.g. with two cores, you would want ``make -s -j2``).
+
+Once Python is done building you will then have a working build of Python
+that can be run in-place; ``./python`` on most machines, ``./python.exe``
+on OS X.
+
+Windows
+'''''''''''''''''''''''''
+
+For VC 9 and newer, the ``PCbuild`` directory contains build files you will
+care about. For older versions of VC, see the ``PC`` directory. For a free
+compiler for Windows, go to http://www.microsoft.com/express/ .
+
+To build from the GUI, load the project files and press F7. Make sure to
+choose the Debug build. If you want to build from the command line, run the
+``build_env.bat`` file to get a terminal with proper environment variables.
+From that terminal, run::
+
+ build.bat -c Debug
+
+Once built you will want to set Python as a startup project. F5 will
+launch the interpreter as well as double-clicking the binary.
+
+
+Editors and Tools
+=====================================================================
+
+What support is included in Python's source code for Vim?
+---------------------------------------------------------
+
+Within the ``Misc/Vim`` directory you will find two files to help you when
+editing Python code. One is ``python.vim``, which is a generated syntax
+highlight file for Python code. This file is updated much more frequently as it
+contains syntax highlighting for keywords as they are added to the source tree.
+See the top of the file to find out how to use the file.
+
+The other file for Vim is a vimrc file that supports PEP 7 and 8 coding
+standards. All settings are specific to Python and C code and thus will not
+affect other settings. There are also some settings which are helpful but
+turned off by default at the end of the file if one cares to use non-essential
+settings. Once again, see the top of the file to learn how to take advantage of
+the file.
+
+
+What support is included in Python's source code for gdb?
+----------------------------------------------------------
+
+The ``Misc/gdbinit`` file contains several helpful commands that can be added
+to your gdb session. You can either copy the commands into your own
+``.gdbinit`` file or, if you don't have your own version of the file, simply
+symlink ``~/.gdbinit`` to ``Misc/gdbinit``.
+
+
+Can I run Valgrind against Python?
+----------------------------------
+
+Because of how Python uses memory, Valgrind requires setting some supression
+rules to cut down on the false positives (which still come up, suggesting one
+typically should know how Python uses memory before running Valgrind against
+Python). See ``Misc/README.valgrind`` for more details.
+
+
+Patches
+=====================================================================
+
+How to make a patch?
+-------------------------
+
+
+If you are using subversion (anonymous or developer) you can use
+subversion to make the patches for you. Just edit your local copy and
+enter the following command::
+
+ svn diff | tee ~/name_of_the_patch.diff
+
+Else you can use the diff util which comes with most operating systems (a
+Windows version is available as part of the cygwin tools).
+
+
+How do I apply a patch?
+-------------------------
+
+For the general case, to apply a patch go to the directory that the patch was
+created from (usually /dist/src/) and run::
+
+ patch -p0 < name_of_the_patch.diff
+
+The ``-p`` option specifies the number of directory separators ("/" in the
+case of UNIX) to remove from the paths of the files in the patch. ``-p0``
+leaves the paths alone.
+
+
+How do I undo an applied patch?
+-------------------------------
+
+Undoing a patch differs from applying one by only a command-line option::
+
+ patch -R -p0 < name_of_the_patch.diff
+
+Another option is to have 'patch' create backups of all files by using the
+``-b`` command-line option. See the man page for 'patch' on the details of
+use.
+
+
+How to submit a patch?
+---------------------------
+
+Please consult the patch submission guidelines at
+http://www.python.org/patches/ .
+
+
+How to test a patch?
+------------------------------
+
+Firstly, you'll need to get a checkout of the source tree you wish to
+test the patch against and then build python from this source tree.
+
+Once you've done that, you can use Python's extensive regression test
+suite to check that the patch hasn't broken anything.
+
+In general, for thorough testing, use::
+
+ python -m test.regrtest -uall
+
+For typical testing use::
+
+ python -m test.regrtest
+
+For running specific test modules::
+
+ python -m test.regrtest test_mod1 test_mod2
+
+NB: Enabling the relevant test resources via ``-uall`` or something more
+specific is especially important when working on things like the
+networking code or the audio support - many of the relevant tests are
+skipped by default.
+
+For more thorough documentation,
+read the documentation for the ``test`` package at
+http://docs.python.org/library/test.html.
+
+If you suspect the patch may impact other operating systems, test as
+many as you have easy access to. You can get help on alternate
+platforms by contacting the people listed on
+http://www.python.org/moin/PythonTesters, who have
+volunteered to support a particular operating system.
+
+
+How to change the status of a patch?
+-----------------------------------------
+
+
+To change the status of a patch or assign it to somebody else you have to
+have the Developer role in the bug tracker. Contact one of the project
+administrators if the following does not work for you.
+
+Click on the patch itself. In the screen that comes up, there is a drop-box
+for "Assigned To:" and a drop-box for "Status:" where you can select a new
+responsible developer or a new status respectively. After selecting the
+appropriate victim and status, hit the "Submit Changes" button at the bottom
+of the page.
+
+Note: If you are sure that you have the right permissions and a drop-box
+does not appear, check that you are actually logged in to Roundup!
+
+
+Bugs
+=====================================================================
+
+Where can I submit/view bugs for Python?
+---------------------------------------------
+
+
+The Python project uses Roundup for bug tracking. Go to
+http://bugs.python.org/ for all bug management needs. You will need to
+create a Roundup account for yourself before submitting the first bug
+report; anonymous reports have been disabled since it was too
+difficult to get in contact with submitters. If you previously
+had used SourceForge to report Python bugs, you can use Roundup's
+"Lost your login?" link to obtain your Roundup password.
+
+.. XXX this is heavily outdated
+
+ Appendix A
+ ================
+
+ Issue Manager Guidelines
+ -------------------------------
+
+ In general, the Resolution and Status fields should be close to
+ self-explanatory, and the "Assigned to:" field should be the person
+ responsible for taking the next step in the patch process. Both fields
+ are expected to change value over the life of a patch; the normal
+ workflow is detailed below.
+
+ When you've got the time and the ability, feel free to move any patch that
+ catches your eye along, whether or not it's been assigned to you. And if
+ you're assigned to a patch but aren't going to take reasonably quick action
+ (for whatever reason), please assign it to someone else ASAP: at those times
+ you can't actively help, actively get out of the way.
+
+ If you're an expert in some area and know that a patch in that area is both
+ needed and non-controversial, just commit your changes directly -- no need
+ then to get the patch mechanism involved in it.
+
+ You should add a comment to every patch assigned to you at least once a
+ week, if only to say that you realize it's still on your plate. This rule is
+ meant to force your attention periodically: patches get harder & harder to
+ deal with the longer they sit.
+
+
+ Status Open, Resolution None
+ '''''''''''''''''''''''''''''''''
+
+ The initial state of all patches.
+ The patch is under consideration, but has not been reviewed yet, or
+ s under review but not yet Accepted or Rejected.
+
+ The Resolution will normally change to Accepted or Rejected next.
+ The person submitting the patch should (if they can) assign it to the person
+ they most want to review it.
+
+ Else the patch will be assigned via [xxx a list of expertise areas should be
+ developed] [xxx but since this hasn't happened and volunteers are too few,
+ andom assignment is better than nothing: if you're a Python developer,
+ expect to get assigned out of the blue!]
+
+ Discussion of major patches is carried out on the Python-Dev mailing list.
+ For simple patches, the SourceForge comment mechanism should be sufficient.
+ [xxx an email gateway would be great, ditto Ping's Roundup]
+ For the reviewer: If you're certain the patch should be applied,
+ change the Resolution to Accepted and assign it back to the submitter (if
+ possible) for checkin. If you're certain the patch should never be
+ accepted, change the Resolution to Rejected, Status to Closed, and assign it to None.
+
+ If you have specific complaints that would cause you to change your mind,
+ explain them clearly in a comment, leave the status Open, and reassign
+ back to the submitter. If you're uncertain, leave the status Open, explain
+ your uncertainties in a comment, and reassign the patch to someone
+ you believe can address your remaining questions; or leave the status
+ Open and bring it up on Python-Dev.
+
+
+ Status Open, Resolution Accepted
+ '''''''''''''''''''''''''''''''''''''
+
+ The powers that be accepted the patch, but it hasn't been applied yet. [xxx
+ flesh out -- Guido Bottleneck avoidable here?]
+
+ The Status will normally change to Closed next.
+
+ The person changing the Resolution to Accepted should, at the same time, assign
+ the patch to whoever they believe is most likely to be able & willing to
+ apply it (the submitter if possible).
+
+
+ Status Closed, Resolution Accepted
+ '''''''''''''''''''''''''''''''''''''''''
+
+ The patch has been accepted and applied.
+
+ The previous Resolution was Accepted, or possibly None if the submitter was
+ Guido (or moral equivalent in some particular area of expertise).
+
+ Status Closed, Resolution Rejected
+ '''''''''''''''''''''''''''''''''''''''''
+
+ The patch has been reviewed and rejected.
+
+ There are generally no transitions out of this state: the patch is dead.
+
+ The person setting this state should also assign the patch to None.
+
+
+ Status Open, Resolution Out of date
+ ''''''''''''''''''''''''''''''''''''''''''
+
+ Previous Resolution was Accepted or Postponed, but the patch no longer
+ works.
+
+ Please enter a comment when changing the Resolution to "Out of date", to record
+ the nature of the problem and the previous state.
+
+ Also assign it back to the submitter, as they need to upload a new version.
+
+
+ Status Open, Resolution Postponed
+ '''''''''''''''''''''''''''''''''''''''''
+
+ The previous Resolution was None or Accepted, but for some reason (e.g., pending
+ release) the patch should not be reviewed or applied until further
+ notice.
+
+ The Resolution will normally change to None or Accepted next.
+
+ Please enter a comment when changing the Resolution to Postponed, to record the
+ reason, the previous Resolution, and the conditions under which the patch should
+ revert to Resolution None or Accepted. Also assign the patch to whoever is most likely
+ able and willing to decide when the state should change again.
+
Added: sandbox/trunk/dev/index.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/index.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,21 @@
+
+###################################
+ Developer's Guide
+###################################
+
+:Release: |version|
+:Date: |today|
+
+.. toctree::
+ :maxdepth: 1
+
+ why.rst
+ tools.rst
+ setup.rst
+ contributing.rst
+ culture.rst
+ process.rst
+ workflow.rst
+ patches.rst
+ faq.rst
+
Added: sandbox/trunk/dev/patches.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/patches.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,52 @@
+
+========================================
+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
+ before submitting a patch, or else the 'Create New'
+ link will not appear.
+
+* Submit documentation patches 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>.
+
+* 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 way 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
+ 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, 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>`_.
+
Added: sandbox/trunk/dev/process.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/process.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,117 @@
+==============================
+Python's Development Process
+==============================
+
+Guido van Rossum is the project's lead developer. In recognition
+of this role, he's sometimes jokingly called the Benevolent Dictator
+For Life, or BDFL; the acronym is occasionally used in python-dev
+postings, especially in a context such as "making that change will
+require a BDFL pronouncement". In theory the BDFL makes all the
+decisions about what goes in to Python and what doesn't. In practice,
+Guido will often defer to someone else's expertise in a specialized
+domain; for example, Tim Peters is the resident master of floating
+point arcana, Jeremy Hylton usually wrestles the Python compiler, and
+so forth. Modules in the standard library are also often the
+responsibility of a particular individual who's the first choice to
+review patches or fix bugs in it, but anyone can modify any line of
+code at any time, and simple, obviously correct fixes can be applied
+by anyone.
+
+An informal voting process is sometimes followed on python-dev.
+People will sometimes post their votes in response to a suggestion,
+giving them as +1, -1, +0, or -0. This numbering comes from `the voting scheme used by Apache <http://dev.apache.org/guidelines.html>`_:
+
+ * +1 indicates that the poster is in favor of the suggestion.
+ * -1 indicates they're against it.
+ * +0 indicates "I don't care, but go ahead".
+ * -0 means "I don't care, so why bother?".
+
+In the Apache project, this
+voting is formalized and is how binding project decisions are made,
+but in
+Python it's just a concise way to express opinions in a straw poll
+and the result isn't binding in any way. The BDFL will take note of
+the reaction to a proposal, but is free to ignore it. While the BDFL
+could completely ignore community reaction, I can't think of an instance
+where he's actually done so in the face of united disapproval by the
+community. The closest case to that might be the ``print >>``
+statement, where everyone turned out to be divided 50/50 between
+liking it and hating it. Guido exercised his right to decide, and
+the feature was added to the language in Python 2.0. Some people
+still hate it; some people who first argued against it have now grown
+sneakily fond of it.
+
+PEPs
+==============
+
+
+Because Python is a programming language and there are a few
+million lines of Python code in the world, the development process has
+to impose some rigidity and provide some resistance against accepting
+changes too easily. Users have Python code, extension modules written
+in C, and applications that embed Python, so it's important that the
+inconvenience of upgrading to new versions of Python is minimized.
+Language changes might also make the language too difficult for new
+users to learn.
+
+As a way to ensure that changes are carefully considered,
+significant changes *must* be described in a Python Enhancement
+Proposal, or PEP. PEPs are modelled on the Request For Comments
+documents used by the Internet Engineering Task Force, and describe a
+proposed change by giving fairly complete documentation for it and a
+design rationale. PEPS also record the community's consensus about a
+feature, because the PEP's author must take note of people's comments
+and incorporate their feedback. PEPs are especially important if the
+suggested feature gets rejected, because the same ideas often come
+back again and again, resulting in lengthy discussion threads that
+always arrive at the same outcome. (For example, ideas such as not
+using indentation, adding a *with* statement, or support for
+interfaces often come up again and again.) Like a FAQ, which tries to
+reduce newsgroup traffic by answering questions before they're asked,
+PEPs try to reduce repeated suggestions.
+
+All the PEPs are available online at `http://www.python.org/dev/peps/ </dev/peps/>`_.
+PEP 1, `PEP Purpose and Guidelines </dev/peps/pep-0001/>`_ explains the purpose of PEPs, their life
+cycle, and the prescribed format for a PEP. Read it before beginning
+to write a PEP.
+
+Documenting Python
+============================
+
+
+Any significant additions to the Python core must be accompanied by
+supporting patches for the documentation. Python's documentation is,
+as of version 2.6, written using `docutils`_\' reStructuredText and an
+accompanying builder application that converts the source to
+PDF, HTML, or PostScript. Georg Brandl, the author of the builder,
+has written the new `"Documenting Python" <http://docs.python.org/dev/documenting/>`_,
+containing a quick introduction to reStructuredText and a guide to
+the Python-specific markup.
+
+You should also write helpful docstrings for modules, because the
+`pydoc <http://docs.python.org/library/pydoc>`_
+module provides online help generated from module docstrings. Writing
+docstrings is therefore an easy way to make life easier for users.
+
+.. _docutils: http://docutils.sf.net/
+
+
+Recording Change
+==========================
+
+
+The file Misc/NEWS is the traditional place to record all changes to
+the Python code. This file is intended to be a complete record of changes
+between versions, and therefore useful for (among other purposes) finding
+the source of compatibility issues.
+
+Misc/NEWS is also scanned before each release as the source of the
+"What's new in Python X.Y" documents, created from whatsnewXY.tex.
+This document is a fuller description of only the more significant
+changes to the language. Developers are welcome to add descriptions
+of their own changes to whatsnewXY.tex, but not at the expense of
+omitting change descriptions in Misc/NEWS.
+
+If you only have time to do one thing, record your changes in the
+Misc/NEWS file.
+
Added: sandbox/trunk/dev/setup.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/setup.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,121 @@
+==================================================
+Setting Up for Developing Python
+==================================================
+
+
+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.
+
+.. contents::
+
+.. _dev FAQ: http://www.python.org/dev/faq/
+
+
+Checking out the code
+=====================
+
+Python always has the in-development version of the current major versions
+along with the last minor release of each major version. For instance, if
+Python 2.6 was the latest release (and thus has a major version of *2* and a
+minor version of *6*), then the in-development 2.7 branch is available along
+with the maintenance branch for 2.6.
+
+For each branch there is read-only access for the general public and read-write
+access for those with commit privileges (called "core developers"). The
+location of these branches and the steps to check out the code are listed in
+the `dev FAQ`_.
+
+
+Compiling for debugging
+=======================
+
+Python has two features to aid in developing for it. First, there is a
+``Py_DEBUG`` compilation flag which turns on some features in the interpreter
+which will help with debugging. While this is not the only compilation flag
+available (see ``Misc/SpecialBuilds.txt`` in a checkout for all of them), it is
+the basic one that you should always use as it tends to catch bugs more often
+than running a build of Python without the flag.
+
+The other feature is support for using code directly from a checkout of Python.
+This is handy as it means you do not need to install your build of Python but
+can just use the build in-place. It also means that when you edit code in your
+checkout you get to see the results without having to install the changed files
+as well.
+
+The steps to compile a debug version of Python are specified in the `dev FAQ`_.
+
+
+Editors and Tools
+==================
+
+Python includes within its source tree some files to help work with various
+popular editors and tools. A list of those tools and what is available for them
+can be found in the `dev FAQ`_.
+
+
+Directory Structure
+===================
+
+There are several top-level directories in the Python source tree. Knowing what
+which one is meant to hold will help you find where a certain piece of
+functionality is implemented. Do realize, though, there are always exceptions to
+every rule.
+
+``Demo``
+ Example code goes here. This directory is not well-maintained and thus
+ should not be considered best-of-breed in terms how best to accomplish
+ something with the newest version of Python.
+
+``Doc``
+ The official documentation. This is what http://docs.python.org/ uses. The
+ tools for building the documentation is kept in another repository. To
+ build the docs, see ``Doc/README.txt``.
+
+``Grammar``
+ Contains the EBNF grammar file for Python.
+
+``Include``
+ Contains all interpreter-wide header files.
+
+``Lib``
+ The part of the standard library implemented in pure Python is here.
+
+``Mac``
+ Mac-specific code for things such as using IDLE as an OS X application.
+
+``Misc``
+ Things that do not belong elsewhere. Typically this is varying kinds of
+ documentation.
+
+``Modules``
+ The part of the standard library (plus some other code) that is implemented
+ as extension modules.
+
+``Objects``
+ Code for all built-in types.
+
+``PC``
+ Windows-specific code along with build files for VC 6, 7, & 8 along with
+ OS/2.
+
+``PCbuild``
+ Build files for VC 9 and newer.
+
+``Parser``
+ Code related to the parser. The definition of the AST nodes is also kept
+ here.
+
+``Python``
+ The code that makes Python run. This includes the compiler, eval loop and
+ various built-in modules.
+
+``RISCOS`` : Not in Python 3.0
+ RISC-specific files.
+
+``Tools``
+ Various tools that are (or have been) used to maintain Python.
+
Added: sandbox/trunk/dev/tools.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/tools.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,159 @@
+
+====================
+Development Tools
+====================
+
+
+SVN Tree
+==================
+
+
+The Python source code is stored in the Subversion, or SVN, version
+control system.
+
+Anyone can check out a read-only copy of the source tree by using
+anonymous SVN. To check out the tree::
+
+ 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.
+
+For information about SVN, see "Version Control with Subversion"
+at http://svnbook.red-bean.com/.
+
+Check-in Policies
+```````````````````````````
+
+
+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
+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.
+
+If you're granted SVN write access, you have to follow a few simple
+rules.
+
+* 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 checking in a code change, re-run the entire Python test
+ suite to be sure that you haven't broken anything. To run the
+ complete test suite, use the following command from the top
+ directory of the source tree::
+
+ ./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 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.
+
+* When a patch changes behavior or fixes a noteworthy bug, you
+ should add an entry to the ``Misc/NEWS`` file about the
+ change. The file is divided into sections for the core and built-ins,
+ extension modules, the standard library, and accompanying tools,
+ and a change should be described in the appropriate section.
+ Optionally you can add a note about the change to the "What's New in
+ Python" document in ``Doc/whatsnew/``; see the comments at the top
+ of that file for instructions.
+
+* Simple or trivial fixes can be just checked in. This is
+ especially true if it's for code or documentation that you own, but
+ you can make a change to another person's module; code ownership is
+ not particularly strict on the Python project. Just be very sure that
+ 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.
+ Instead, create a patch in the patch tracker (see below) and discuss
+ the patch with the other developers until everyone agrees it's
+ correct.
+
+* The previous rule applies even more strongly to large patches
+ that touch many files or make far-reaching changes. The Python source
+ tree is managed for stability, meaning that if you make a checkout at
+ a random point in time the tree will almost always compile and be
+ quite stable. Large sets of changes, such as the 2.2 type/class
+ rewrite, are usually tested on a branch first and merged into the main
+ stream of development once they're believed to be complete.
+
+* Before new releases, code freezes will be announced on
+ python-dev. Obey them and don't make checkins without getting
+ approval on the ``python-dev`` list first.
+
+
+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
+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.
+
+
+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
+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>`_.
+
+
+URL Redirectors
+=========================
+
+The canonical URL of a bug report is
+
+ http://bugs.python.org/issue1010
+
+This would be the link for bug #1010. A slightly shorter form
+is available through a redirect, as simply
+
+ http://bugs.python.org/1010
+
+From the times 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.
Added: sandbox/trunk/dev/why.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/why.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,84 @@
+====================
+Why Develop Python?
+====================
+
+Why would you want to work on the Python core interpreter?
+
+* You might be a Python user who wants to make Python more useful
+ for your purposes.
+
+* You enjoy hacking on sizable software systems in general, or
+ perhaps language interpreters in particular.
+
+* You want to gain experience as a developer on an open source
+ project.
+
+ From time to time you can see postings in various online forums from
+ programmers who want to get experience developing a free software
+ project. Many programmers go off and start their own
+ project by beginning a new IRC client, mail program, or some similar
+ application. However, the chances of making a useful contribution
+ are better if you join an existing sizable project that's already
+ successful. It'll also be more educational because a
+ well-established project will teach you skills that aren't called
+ into play for a smaller project.
+
+Python is an excellent project choice for the following reasons:
+
+* Because Python is a large project, there are many available
+ tasks suitable for different temperaments and skill levels. If you
+ enjoy writing prose and explaining things, you can write
+ documentation. If you can program in Python (and it isn't difficult
+ to learn), you can work on the library modules, tools, and demo
+ programs that are included with the Python distribution. If you can
+ program in C, you can write extension modules or hack on the
+ interpreter itself. If you'd rather inspect someone else's code
+ than write your own, you can examine submitted patches or fix bugs.
+
+ You certainly do not have to be a highly skilled wizard who can
+ rewrite the entire interpreter at the drop of a hat in order to
+ contribute. There are many things you can do on the spectrum
+ of tasks ranging from simple to complex ones.
+
+* First released in 1991, Python's development process is quite mature
+ at this point. The project has a public Subversion repository, a
+ coding standard for both C and Python code, a framework for writing
+ test suites, and infrastructure for tracking bug reports and
+ 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.
+
+* 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 whom are very active and make the bulk
+ of actual commits, and the rest of whom make occasional
+ checkins and provide opinions and advice. Lots of people outside
+ this core group contribute significantly, too; bug reports and
+ patches come from core developers, well-known Python users, and
+ complete strangers.
+ The list of active members is always shifting because
+ developers have differing free time, availability, and interests.
+
+ To work with this large and dispersed group, you'll have to learn
+ who's the right person to answer a question, how to convince the
+ other developers of the usefulness of a patch, how to offer helpful
+ criticism, and how to take criticism.
+
+* C programmers will find that the C source code for the Python
+ interpreter is clearly written and easy to dive into. It's
+ relatively easy to familiarize yourself with the code, and to begin
+ writing extensions, making changes, or porting it to a new platform.
+
+Note that it's possible to do a lot even if you don't know
+C at all. Working on the portions of the standard library that are
+written in Python is just as valuable for the project and is equally
+educational for you. Plus, programming in Python is much more
+pleasant than programming in C, because you get nicely formatted
+tracebacks instead of nasty core dumps and protection faults.
+
+Most of the Python core developers seem to be on Unix, but there
+are a number of Windows and MacOS programmers. There's always room
+for more developers, no matter what platform, so don't hesitate to
+jump in.
Added: sandbox/trunk/dev/workflow.rst
==============================================================================
--- (empty file)
+++ sandbox/trunk/dev/workflow.rst Thu Sep 24 13:43:13 2009
@@ -0,0 +1,250 @@
+
+====================
+Issue Workflow
+====================
+
+Below are the typical steps taken to resolve an issue filed on
+`issue tracker`_. The section titles follow the *Stage* field of an issue
+except when in square brackets. It is assumed you have already read
+`Getting Set Up`_.
+
+.. _issue tracker: http://bugs.python.org/
+.. _Getting Set Up: /dev/setup
+
+
+[New issue]
+===========
+
+When you file an issue, the issue should be explained as best as possible. The
+more that can be said upfront the faster the issue can be dealt with as there
+will be less of a chance someone needs more details later on.
+
+With the new issue created, emails are sent out to the new-bugs-announce_ and
+python-bugs-list_ mailing lists. The former receives a single email for all
+created issues while the latter receives an email for any change made to an
+issue. This way people who are interested in potentially working on issues are
+quickly and easily notified when issues come in.
+
+.. _new-bugs-announce: http://mail.python.org/mailman/listinfo/new-bugs-announce
+.. _python-bugs-list: http://mail.python.org/mailman/listinfo/python-bugs-list
+
+
+[triage]
+========
+
+Once a new issue has been created it needs to go through triage. This means all
+fields in the issue tracker need to be set properly. While most of the fields
+are self-explanatory, some need a little explanation:
+
+Type
+----
+
+Behavior
+ Something does not have the expected semantics.
+
+Compile error
+ When the issue relates to compilation specifically.
+
+Crash
+ Something is causing the interpreter to crash, e.g. a segfault, bus error,
+ etc.
+
+Feature request
+ A request to add or change something in Python.
+
+Performance
+ A performance regression.
+
+Resource usage
+ A resource usage regression.
+
+Security
+ Somehow someone is able to gain escalated privileges when they shouldn't be
+ able to.
+
+
+Versions
+--------
+
+This field represents what versions an issue is known to affect and should be
+fixed on. This has the effect that what versions an open issue lists are the
+ones that the issue explictly needs to be fixed on. As the issue is fixed on
+various versions they can be removed from the versions list in order to make it
+easily known what backporting is still required.
+
+
+Priority
+--------
+release blocker
+ The next release of Python, whether it be an alpha or release candidate,
+ will not happen unless this issue is closed.
+
+deferred blocker
+ While an issue of this priority will not hold up this release, it will hold
+ up the next one.
+
+critical
+ A **critical** issue will most likely block a release, just not necessarily
+ the next one.
+
+high
+ No release will be held up for an issue of this priority, but the issue
+ should still be addressed when possible.
+
+normal
+ In no way critical but requiring some though.
+
+low
+ Simple issues, e.g. spelling errors in the documentation.
+
+Nosy list
+---------
+If a specific developer should look at an issue, it is completely acceptable to
+add them to the *Nosy List* without asking for permission. This is important as
+not all developers subscribe to either of the bug announcement lists and thus
+will not see all updates to an issue. By adding someone to the nosy list they
+will receive an email to catch their attention.
+
+Keywords
+---------
+For *Keywords*, the **easy** keyword should be set if an issue can be handled
+by someone with no deep knowledge of how Python works. Typically this is fixing
+shallow bugs, clearing up some semantics, writing tests, etc. These issues can
+be solved in a few hours, e.g. within the timespan of a single bug day.
+
+Setting this field is important! Having **easy** issues allows people who wish
+to help out have an easy time finding issues to work on that they will
+(hopefully) not be frustrated by and thus have a gradual introduction to how
+development for Python works.
+
+
+[Unit] Test needed
+==================
+
+To help verify an issue is still a problem and have it easily reproduced, an
+automated test is needed. It needs to be succinct and, if possible, execute
+quickly. Every bug fix or semantic change needs some test, whether it is a new
+test or a tweak of an existing one. But no new code should ever be checked in
+without some test to exercise the new code! And having a bug available as a
+patch against Python's test suite makes it easier to verify when a patch fixes
+the issue.
+
+As with all new code, the style guides of `PEP 8`_ and `PEP 7`_ should be
+followed. For modules their tests live in ``Lib/test`` which corresponds to the
+``test`` package in Python. For packages a driver script can be put into
+``Lib/test`` that runs tests contained in a subpackage of the package being
+tested.
+
+To run a test, you have two options. One is to execute the test directly
+(``./python Lib/test/test_grammar.py``). The other option is to use the
+``regrtest.py`` test driver which you give the name of the module as contained
+in the ``test`` package (``./python Lib/test/regrtest.py test_grammar``). If
+you run ``regrtest.py`` without specifying a test then all tests are run. Run
+``regrtest.py`` with the ``-h`` flag to see all of the options it provides, but
+the most important is the ``-u`` flag to turn on resource usage. To run
+Python's entire test suite, run ``./python Lib/test/regrtest.py -uall``.
+
+Test code can be written using doctest_ or unittest_. Which one is used is left
+up to personal preference or what a set of tests for a module is already
+written in. For support code beyond what doctest and unittest provide, see
+``test.support`` (named ``test.test_support`` in Python 2.x). While not
+thoroughly documented on purpose, there is several bits of code in there to
+help out with testing.
+
+.. _PEP 7: http://www.python.org/dev/peps/pep-0007/
+.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
+.. _doctest: http://docs.python.org/dev/library/doctest.html
+.. _unittest: http://docs.python.org/dev/library/unittest.html
+
+
+Needs patch
+===========
+
+If the issue is a bug, then a patch is needed to fix it. The `PEP 7`_ and
+`PEP 8`_ style guides need to be followed. Tests should have already been
+written, if needed, by the **test needed** stage. A unified diff is preferred
+and should be automatic if you followed the `Getting Set Up`_ docs.
+
+Any changes need to not only pass their own tests, but also the entire test
+suite (``./python Lib/test/regrtest.py -uall``). This makes sure that no
+change, no matter how small, does not break other code that may have been
+relying on old behavior.
+
+An issue can end up back at this stage if a pre-existing patch has problems.
+Always read the comments on an issue to see what has led to the current state
+of the issue. An issue can also seem to belong on this stage if there is a
+patch but actually belong to **test needed** because a test is missing.
+
+Once a patch is written, it is helpful to also add it to Rietveld_. The code
+review tool provides an ``upload.py`` script to help you upload the patch
+directly. Simply paste in the link that Rietveld gives you in a message on the
+issue and then reviews of your patch can utilize Rietveld.
+
+.. _Rietveld: http://codereview.appspot.com/
+
+
+[Docs needed]
+=============
+
+If any semantics are changed because of a patch or the issue is to make a
+change to the docs then documentation changes are needed. `Documenting Python`_
+specifies how the markup works. How to compile Python's documentation is
+outlined in the `Getting Set Up` documentation.
+
+.. _Documenting Python: http://docs.python.org/dev/documenting/
+
+
+Patch review
+============
+
+If an issue reaches this stage then someone believes that the code is ready to
+be reviewed for checking. All steps outlined in the other stages should have
+been followed: there are tests if needed, all code follows the style
+guidelines, the code is of high quality, and any needed docs changes have been
+made. There should also be an entry for ``Misc/NEWS`` and ``Misc/ACKS`` as
+needed.
+
+Anyone can comment on an issue that has reached this stage, not just
+developers! If you think a change is needed or that the patch looks good then
+please say so!
+
+This stage is typically where an issue languishes on the issue tracker. Because
+there are only so many developers and almost all of them volunteer their free
+time to work on Python, there is simply not enough collective time to usually
+get a patch review done promptly. This does not mean your patch will never be
+reviewed or is not appreciated! It simply means people are busy with other
+things which include "real life". Please be patient if your patch takes a
+while to be reviewed.
+
+If the OP of the patch didn't do so, feel free to use Rietveld_ for a patch
+review. It can greatly simplify the review process for both you and the patch
+creator.
+
+
+Commit review
+==============
+
+Setting the stage to this value means that the issue cannot move any forward
+without a review by a core developer. This can come up in two situations.
+
+When the next release of Python is a release candidate or a final release,
+issues need to reviewed by two core developers before being checked in, as this
+stage represents. If a patch was written by a core developer than the issue can
+skip over the `patch review`_ stage directly to this . But if a patch was done
+be a non-core developer it must first pass through the `patch review` stage and
+be reviewed by a core developer at that stage as well. This guarantees all new
+code is reviewed by at least two core developers before being committed,
+preventing any new bugs from slipping into an RC or final release.
+
+Another situation is that someone performing triage on an issue notices that a
+patch has already been properly reviewed by a non-core developer and thus is
+ready to be seriously looked at for being applied. By setting a stage to this
+value should act as a flag to core developers that a patch is as ready as it's
+going to be for a commit review.
+
+
+Committed/rejected
+==================
+
+At this point the issue is closed. Either it was accepted/fixed or rejected for
+some reason.
More information about the Python-checkins
mailing list