[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
Brett Cannon
brett at python.org
Thu Sep 24 22:44:12 CEST 2009
So should I start doing all of my work here, or still over in pydotorg?
On Thu, Sep 24, 2009 at 04:43, andrew.kuchling
<python-checkins at python.org> wrote:
> 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.
> _______________________________________________
> Python-checkins mailing list
> Python-checkins at python.org
> http://mail.python.org/mailman/listinfo/python-checkins
>
More information about the Python-checkins
mailing list