<<TableOfContents>>

= Getting Your Own python-dev Tracker =

This page describes how to setup a roundup tracker instance that works
exactly as the tracker for python-dev on http://bugs.python.org. The
intended audience is people that want to help out with the tracker,
developing new features etc.

== Requirements ==

 * Roundup, from the vendor branch used for python-dev (see below).

 * PostgreSQL for use as backend database.

 * Installation of psycopg.

 * A checkout of the spambayes_integration.

 * A checkout of the python-dev instance from python's subversion
repository.

== Installing roundup ==

For python-dev, we use a slightly modified version of Roundup which has
some features that are not yet in the core Roundup. To keep track of
the changes, we keep a vendor branch of roundup.

Check out
[[http://svn.python.org/view/tracker/roundup-src|/tracker/roundup-src]]
from the python subversion
repository as documented on http://python.org/dev/tools/. For
example, here's how to do anonymous checkout:

{{{
  svn co http://svn.python.org/projects/tracker/roundup-src
}}}

Install this roundup somewhere by running setup.py

{{{
  cd roundup-src
  python setup.py install --prefix /opt/tracker-roundup/
}}}

== Install and configure PostgreSQL ==

For the python-dev tracker instance we use PostgreSQL as backend
database. Roundup has support for many different databases for backend
(anydbm, metakit, MySQL, PostgreSQL, SQLite...), but for the python-dev
instance, PostgreSQL was selected as it has the best performance for
large installations. Also, for performance reasons, there is at least
one place in the python-dev instance that has a hardcoded dependency
on the backend being an SQL-based one, so you do need PostgreSQL even
for development work (another SQL-based backend might work, but this
has not been tested). I recommend that you run postgreSQL to make your
development environment behave exactly like the environment the real
tracker runs in.

Details on how to install PostgreSQL is outside the scope of this Wiki
Page. Both version 7.4 and 8.1 of PostgreSQL has been tested without
any known problems. It has been reported that 8.2 and 8.3 work well.

Access configuration of postgresql can be tricky. You need to make
sure that the user you're running roundup as (your unix/windows user)
has access to the postgresql database you intend to use for roundup,
as the postgresql user you've configured in roundup's configuration.

For a development environment with no demands on security, the easiest
way to configure this is probably to allow all users to connect as any
database user as long as the request originates from the local
host. This can be accomplished by the following lines in pg_hba.conf:

{{{
local   all         all                                             trust
host    all         all         127.0.0.1         255.255.255.255   trust
}}}

'''PLEASE NOTE''': This is not a secure configuration on a multi-user
machine.

After the change in pg_hba.conf, reload your postgreSQL database to
make sure it knows about your new access
configuration. Something similar to ''/etc/init.d/postgresql reload''
should do the trick on Unix-like platforms.

Create a database user that is allowed to create databases. This user
will be used when roundup connects to the database.

{{{
# psql -U postgres
postgres=# create user roundup;
postgres=# alter user roundup with createdb;
}}}

== Installing psycopg or psycopg2 ==

You need to install psycopg or psycopg2. Download it from
http://www.initd.org, as pre-packaged versions have been reported to
cause problems.

== Checkout spambayes_integration ==

Even if you don't intend to use the !SpamBayes detector you must still
check out the {{{spambayes_integration}}} instance.
{{{
  svn co
http://svn.python.org/projects/tracker/instances/spambayes_integration
}}}

If you do intend to use it, you will need to also [[#SpamBayesSetup |
install SpamBayes proper and configure it appropriately]]. Otherwise, a
[[#SpamBayesdummyconfiguration |dummy configuration]] should work.



== Checkout and Configure your Development Roundup Instance ==



The [[http://svn.python.org/view/tracker/instances/python-dev/
|python-dev]] tracker instance is version-controlled with subversion,
and resides in the python subversion repository.

{{{
  svn co http://svn.python.org/projects/tracker/instances/python-dev
}}}

Keep in mind that the python-dev instance has relative symlinks to
{{{../../spambayes_integration/[...]}}}, so if your directory layout is
different you have to update these links:
{{{
extensions/spambayes.py ->
../../spambayes_integration/extensions/spambayes.py

detectors/spambayes.py -> ../../spambayes_integration/detectors/spambayes.py

}}}

Now enter the python-dev directory, and create the 'db' directory (not
in svn as it's just to much fuzz to keep it there - every time you run
''roundup-admin init'' it is removed and recreated, confusing svn who
wants to keep its .svn directory intact), as well as the
db/backend_name file which decides which backend (i.e. database type)
to use:

{{{
cd python-dev
mkdir db
echo postgresql > db/backend_name
}}}

Copy python-dev/config.ini.template into config.ini, and modify it
according to your site. Pay special attention to settings marked with
''NO DEFAULT''. However, if you've configure your PostgreSQL as above,
most settings should be OK.

If you need to do development on the '''busybody''' or '''tellteam'''
detectors,
copy detectors/config.ini.template into detectors/config.ini, and
adjust the e-mail addresses accordingly. <<Anchor(ciavc)>> The
'''CIA.vc''' detector sends emails about issue changes and is on by
default. Disable it by adding a {{{return}}} to its init() function
(detectors/cia.py):


{{{#!python
 def init(db):
     return # <--
     db.issue.react('create', sendcia)
     db.issue.react('set', sendcia)
}}}

Initialize your roundup instance:

{{{
/opt/tracker-roundup/bin/roundup-admin -i <your python-dev directory> init
}}}

Provide a password for the 'admin' user when asked for.

Start your roundup instance:

{{{
/opt/tracker-roundup/bin/roundup-server -p 9999 python-dev=<your
python-dev directory>
}}}

You should now be able to browse http://localhost:9999/python-dev/ and
get a roundup instance that looks just like http://bugs.python.org,
except for some missing new values for fields like Stages and Keywords.
It's possible to replace '''initial_data.py'''  with an
[[attachment:initial_data_updated.py | updated version]] so that your
fields will have values that match those currently present in the Python
Tracker.

The IDs for values in a given field might be different from those in the
Python Tracker. This should only be a problem if you try to import CSV
files from one tracker into the other.

== SpamBayes Setup ==
If you intend to use the !SpamBayes detector to weed out spam from your
tracker you will need to install it and start an instance of its
{{{core_server}}} application.
Briefly:

 * Download and install at least version 1.1a4 of the
[[http://sourceforge.net/projects/spambayes|SpamBayes source]] from
!SourceForge.  If you are running on Windows '''do not''' use the binary
installer!
 * Establish a basic configuration, e.g.:

Devote a directory to it, e.g.:
{{{
 SBDIR=/usr/local/spambayes/core_server  # or whatever...
 mkdir -p $SBDIR
}}}
Create an INI file:
{{{
 cd $SBDIR
 cat > bayescustomize.ini <<EOF
[globals]
verbose:False

[Headers]
include_evidence:True
include_score:True

[Tokenizer]
record_header_absence:True
summarize_email_prefixes:True
summarize_email_suffixes:True
mine_received_headers:True
x-pick_apart_urls:True
x-fancy_url_recognition:False
x-lookup_ip:True
lookup_ip_cache:$SBDIR/dnscache.pck
max_image_size:100000
crack_image_cache:$SBDIR/imagecache.pck

crack_images:True
image_size:True
ocr_engine:gocr
[Classifier]
use_bigrams:False

[Categorization]
ham_cutoff:0.2
spam_cutoff:0.85

[Storage]
persistent_storage_file:$SBDIR/hammie.db
persistent_use_database:pickle
messageinfo_storage_file:$SBDIR/messageinfo.fs

[html_ui]
display_score:True
EOF
}}}
Finally, run it:
{{{
 BAYESCUSTOMIZE=$SBDIR/bayescustomize.ini core_server.py -m XMLRPCPlugin
}}}
 * If you are seeing image spam (this seems not to be a problem with
wiki spam - yet), download and install
[[http://jocr.sourceforge.net/|GOCR]].

== Common Problems ==

=== SpamBayes dummy configuration ===
Incomplete/Missing !SpamBayes setup:: In your detectors/config.ini file
set {{{spambayes_uri}}} to a syntactically valid, but nonexistent URI, e.g.:

{{{
    spambayes_uri = "http://localhost:9999/nobodyhere"
}}}

Check
[[http://mail.python.org/pipermail/tracker-discuss/2008-February/001549.html
|other available workarounds]].

=== Misbehaving detectors ===
Problematic detectors may be disabled by [[#ciavc |returning from their
init() function]], as was the case of detectors/audit2to3.py (no longer
present). Note that this would be a temporary solution before a graceful
fix became available. Reporting issues with local instances is the best
way help solving the problem.

= Resources for Tracker Development =

== Getting Help ==

Subscribe to and ask your question on the tracker-discuss mailing list.
See http://mail.python.org/mailman/listinfo/tracker-discuss

Since the Python Tracker is a slightly modified version of
[[http://www.roundup-tracker.org |Roundup]], both Roundup's
[[http://www.roundup-tracker.org/docs.html |Documentation]] and
[[http://issues.roundup-tracker.org/ |issue tracker]] contain relevant
information about how the Python Tracker works and problems one might
find working with its code.

== The Meta Tracker ==

A [[http://psf.upfronthosting.co.za/roundup/meta/ |Meta Tracker]] is
available for  handling bugs and features requests for the
[[http://bugs.python.org/ |Python Tracker]].

== Learn more About the Importer(s) ==

http://svn.python.org/projects/tracker/importer/README.rst has some
information about the importer(s) written to convert sourceforge data
into roundup data.

== The Test Tracker ==

Public test instance of the Python tracker: http://bot.bio.br/python-dev/

Instance that attempts to match the code used in http://bugs.python.org
to allow testing, reproducing and verifying fixes for tracker bugs. Can
also be used as a sandbox by users interested in learning about
Developer, Coordinator or Admin tasks and features. Testing new content
(e.g. Components or Statuses) is OK, but new features show be tested in
the Experimental Tracker instead.

Currently the email system is disabled (redirected to file), so people
interested in having an account there to test new features should email
[[http://mail.python.org/mailman/listinfo/tracker-discuss|tracker-discuss]]
to get one. Maintained by DanielDiniz.


== The Experimental Tracker ==

Modified version of the Python tracker: http://bot.bio.br/python-dev-exp/

It's an instance to showcase and test new features.

New features (2009-04-18):
 *
[[http://mail.python.org/pipermail/tracker-discuss/2009-April/002099.html|Issue
tags]]
 * [[http://psf.upfronthosting.co.za/roundup/meta/issue249|Quiet
properties]]
 * [[http://psf.upfronthosting.co.za/roundup/meta/issue267|Restore
removed messages and files]]
 * [[http://psf.upfronthosting.co.za/roundup/meta/issue258|Claim
('assign to self') and add/remove self as nosy buttons]]
 * [[http://psf.upfronthosting.co.za/roundup/meta/issue266|Don't close
issues with open dependencies]]
 * [[http://psf.upfronthosting.co.za/roundup/meta/issue258|Auto-add nosy
users based on Components]]
 * [[http://psf.upfronthosting.co.za/roundup/meta/issue245|"Email me"
buttons for messages and issues, "Reply by email"]]
 * [[http://psf.upfronthosting.co.za/roundup/meta/issue155|RSS feeds
(per issue and global)]]
 * [[http://psf.upfronthosting.co.za/roundup/meta/issue246|Display
selected issues in the index view]]
 *
[[http://psf.upfronthosting.co.za/roundup/meta/issue248|Mass-update/batch-editing
support]]

Currently the email system is disabled (redirected to file), so people
interested in having an account there to test new features should email
[[http://mail.python.org/mailman/listinfo/tracker-discuss|tracker-discuss]]
to get one. Maintained by DanielDiniz.

----
CategoryTracker

This page explains how to use the Python bug tracker:

 * Python tracker: http://bugs.python.org
 * Meta-tracker (bug reporting for the bug tracker):
http://psf.upfronthosting.co.za/roundup/meta/
 * Mailing list about the bug tracker:
http://mail.python.org/mailman/listinfo/tracker-discuss

= Reporting (or fixing) a bug =

=== Reporting ===

Check the SubmittingBugs page for an overview of the bug reporting
process. In a nutshell, it's more important to provide a good
description of the issue than it is to set all fields and options
correctly. Understanding the usual
[[http://www.python.org/dev/workflow/|Issue Workflow]] also helps in
creating good bug reports, raising the chances of your bug report (or
feature request) being resolved efficiently.

=== Fixing and triaging ===

If you want to get started in
[[http://www.python.org/dev/why/|developing Python]], triaging bugs,
writing tests for open issues (or undertested modules) and submitting
patches are great ways to
[[http://www.python.org/dev/contributing/|contribute]].

The [[http://www.python.org/dev/workflow/|Issue Workflow]] doc is even
more important here, as well as taking a look at some
[[http://www.python.org/dev/intro/#general-roundup-guidelines|general
Roundup guidelines]].

= Fields =

== Classification ==

 Title:: Exactly what it sounds like.

 Type:: Specify what kind of issue it is (crasher, compile error, etc.).

 Components:: '''DIFFERENT''': What area of Python is the issue dealing
with?  This section allows for multiple selections.

 Versions:: '''DIFFERENT''': The specific versions that are affected. 
This is a multiple selection box so all known versions that are affected
can be set.

== Process ==

 Status:: '''DIFFERENT''': Specify whether the issue is open, pending
(tentatively closed, but still waiting for OP reaction), or closed.

 Resolution:: Resolution once the issue is in closed or pending state.

 Dependencies:: '''NEW''': If the issue depends on another issue(s),
list them here.  A complete list of issues can be found by clicking on
the ''list'' link.

 Superseder:: '''NEW''': If the issue is superseded by another issue,
list it here.  The ''list'' link pops up a window to help find the
superseding issue.

 Assigned To:: Who is in charge of the issue.

 Nosy List:: '''NEW''': List of usernames who will be notified when
anything changes on the issue.  The original poster (OP) and all
commenters are automatically added.

 Priority:: How quickly must this bug be fixed?  Different from
''Severity'' by specifying how quickly it must be dealt with, not how
severe the issue is.

 Keywords:: '''NEW''': Multiple selection list of keywords to set to
help classify the issue.

  '''26backport''': A 3.0 feature needing backporting to 2.x

  '''patch''': Issue has a patch attached (or was imported from the SF
patches tracker).

  '''64bit''': Bug only applies to 64bit platforms

  '''easy''': A bug that is easy to fix. This might be a good task for a
bug day beginner.

 Change Note:: Add a comment, which will appear as a new Message.

= Learning about Changes =

The tracker will send email messages when a message gets added
(currently not if just a file gets attached, or the status is
changed). These messages get sent to

  * on submission of a new item, to   
[[http://mail.python.org/mailman/listinfo/new-bugs-announce|new-bugs-announce@mail.python.org]],
[[http://mail.python.org/mailman/listinfo/new-bugs-announce|python-bugs-list@python.org]],
and to the assignee (if any)
  * on changes to an item, to python-bugs-list@mail.python.org, and to
all people on the nosy list. Anybody adding a message is automatically
put on the nosy list.

Furthermore, http://bugs.python.org/@@file/recent-changes.xml is updated
for each message or file addition, and can be used to programmatically
track changes.

= Linking from Messages =

The tracker converts some specially formatted words in messages into
links. The list includes

  * "#<number>" links to the issue <number>
  * "msg<number>" links to the message <number>
  * "r<number>, "rev<number>", "revision <number>" links to
svn.python.org displaying the checked in changes.

= Access Control =

A details specification of the access control to the tracker is given in
the table TrackerAccessControl.


= Getting a Developer account under Roundup =

For now, an email to Tracker-discuss (mentioned later) is required for a
non-SF account to become a Developer account (assuming python-dev has
given clearance for the person to have Developer privileges).


= If there is a problem =

If you encounter a problem with the tracker (both in terms of it running
and the transition), please create an issue at the
[[http://psf.upfronthosting.co.za/roundup/meta/|meta tracker]]. 
Tracker-discuss (which is discussed below) will be notified and the
issue will be dealt with as best as possible.

= Improving the Tracker =

Please remember that the initial transition is not meant to drastically
change how issues are handled or reported.  It is simply to get Python's
issue tracker under the control of the PSF.  With that in place,
discussions can begin about improving the handling of issues.

After the transition is complete and stability has been proven then
discussions can begin in earnest to improve the handling of issues.  To
participate in such discussions, please subscribe to the
[[http://mail.python.org/mailman/listinfo/tracker-discuss|tracker-discuss]]
mailing list.  This list is meant to discuss the improvement and
maintenance of the various trackers hosted by python.org.

For information on how to setup your own instance of the python tracker
to help with development, see TrackerDevelopment.

= Logging into Roundup with your SourceForge account =

If you have ever used your SourceForge account on the old Python bug
tracker, you also have a Roundup account. If you have never submitted a
bug to the Python bug tracker, read SubmittingBugs.

To get your new Roundup password,
you need to go through the "forgotten password" procedure (we don't have
access to your SourceForge password). On the tracker, go to
[[http://bugs.python.org/user?@template=forgotten|"Lost your login?"]],
and enter your SF username into the Username field.

This will send you an email (Confirm reset of password for Tracker),
where you need to follow the link. You will get another email (Password
reset for tracker) which contains the new password. The two-email
procedure prevents somebody else maliciously resetting your password.

You then might want to change your password. You can also change the
email address, so that emails won't get sent through sourceforge.net
anymore.

= About Differences between SF and Roundup =

[[http://roundup.sourceforge.net/|Roundup]] is not hugely different from
SourceForge in terms of usage.  Because the initial transition is mostly
for resource reasons (i.e., to control our own tracker), the information
presented for issues is almost identical to what the SF tracker had.

The largest change people will notice, though, are the additions of some
Roundup-specific fields.  Those are denoted with '''NEW''' in their
descriptions below.  All of them help with the management of bugs and
thus should be used when possible and even filled in on existing issues
brought over from SF.

Another change is that of monitoring.  SF had a '''monitor''' button
that subscribed you to an issue so that you always received an email on
all updates.  That is now replaced by the ''nosy list''.  By entering
your username on the nosy list you will receive an email every time the
issue is changed.  More details can be found in the explanation of the
field.

Lastly, Roundup provides an email interface to issues.  This means that
you can actually post to issues by simply replying to an email that you
receive.  This makes posting replies very easy as one does not need to
go through the web interface if the reply does not involve changing
fields or uploading files (which can be done through email as well).


----
CategoryTracker

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

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.

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

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 is a mature programming language which has established a
reputation for stability. In order to maintain this reputation, the
developers would like to know of any deficiencies you find in Python.

Bug reports should be submitted via the Python Bug Tracker
http://bugs.python.org/. The bug tracker offers a Web form which allows
pertinent information to be entered and submitted to the developers.

Filing a Report

The first step in filing a report is to determine whether the problem
has already been reported. The advantage in doing so, aside from saving
the developers time, is that you learn what has been done to fix it; it
may be that the problem has already been fixed for the next release, or
additional information is needed (in which case you are welcome to
provide it if you can!). To do this, search the bug database using the
search tracker box on the top of the page.

Log In

If the problem you're reporting is not already in the bug tracker, go
back to the Python Bug Tracker. If you don't already have a tracker
account, select the Register link in the sidebar and undergo the
registration procedure. If you have an account already, enter your
credentials and select Login. It is not possible to submit a bug report
anonymously.

Once you're logged in, you can submit a bug.

Create an Issue

Select the Create New link in the sidebar to open the bug reporting form.

The submission form has a number of fields.

    *

      Title: enter a *very* short description of the problem; fewer than
ten words is good.
    *

      Type: select the type of your problem (note: rfe stands for
Request for Enhancement).
    *

      Component and Versions: select all appropriate to this bug.
    *

      Change Note: describe the problem in detail, including what you 

expected to happen and what did happen. Be sure to include whether any
extension modules were involved, and what hardware and software platform
you were using (including version information as appropriate).

Click submit

Some pointers to keep in mind:

    *

      Small code examples that don't depend on external code are a great
way to help confirming and fixing the bug you report (providing them as
unittests is ideal, but not required).
    * Precise details about the version(s) and environment in which you
have found the problem make it easier for developers to confirm your report.
    * If you find a bug in previous Python releases, confirming it in
the latest versions helps getting it fixed.
    * Checking whether the issue was previously reported is good, but
duplicates will eventually be merged by triagers.
    * If you find out the issue you submitted is invalid (or a
duplicate), you can close it yourself (or triagers will get to it).
    * For non-conforming behavior bugs, citing the relevant RFCs and
standards is a plus.
    * An objective appraisal of potential or realized harm from the bug
helps developers in prioritizing issues. 

Understanding the usual Issue Workflow also helps in creating good bug
reports, raising the chances of your bug report (or feature request)
being resolved efficiently.

What happens next

See Issue Workflow and general Roundup guidelines for detailed
descriptions of how bugs get fixed.

Each bug report will ultimately be assigned to a core developer who will
determine what needs to be done to correct the problem or take the
necessary steps to include a provided fix or patch into the Python
source. You will receive an email update each time action is taken on
the bug (it's possible to opt-out). Further editing and new messages can
be done by the web form. You can also post to issues by replying to an
email that you receive, file uploads can be done via attachments in this
case.

Contributions in the form of tests, docs and patches are very welcome.
The Developer Documentation is your main guide to the procedures and
tools of the trade. The PythonBugDay volunteer docs offers an overview
focused at newcomer developers.

see also:

How to Report Bugs Effectively
http://www-mice.cs.ucl.ac.uk/multimedia/software/documentation/ReportingBugs.html

    * This article goes into some detail about how to create a useful
bug report. It describes what kind of information is useful and why it
is useful. 

Bug Writing Guidelines
http://www.mozilla.org/quality/bug-writing-guidelines.html

    * Information about writing a good bug report. Some of this is
specific to the Mozilla project, but describes general good practices.

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 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 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. 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"
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, 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".

      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".

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.

I like it :)