# [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

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

==============================================================================
--- (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/

==============================================================================
--- (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.
+* 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.

==============================================================================
--- (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 (Thu, 23 Jul 2009)$
+: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?
+-------------------------------------------------------------------------------
+
+
+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]
+
+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!
+
+.. _PuTTY: http://www.chiark.greenend.org.uk/~sgtatham/putty/
+
+
+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:
+
+=========== ============================================================== ==========================================================================
+----------- -------------------------------------------------------------- --------------------------------------------------------------------------
+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
+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
+
+
+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::
+
+
+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
+
+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
+
+.. 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.
+

==============================================================================
--- (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
+

==============================================================================
--- (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>_.
+

==============================================================================
--- (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.
+

==============================================================================
--- (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.
+

==============================================================================
--- (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.

==============================================================================
--- (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.

==============================================================================
--- (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
+
+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.
`