[Python-Dev] draft for bug guidelines

[Brett Cannon]

Below is the current draft of a set of bug guidelines for people to follow
when they want to file a bug.  The hope is that when we get an email asking
"how do I file a bug?" we can point them towards these sets of guidelines
for most issues.

Let me know about any errors and such.  This will (hopefully) end up going
up on python.org/dev/ eventually.

-------------------------


About
///////////////////////////////////////////////////////////
These sets of guidelines are to help you file a bug report for the
Python programming language on SourceForge_.  If your bug is not for
the language but for a third-party application, please report the bug
to that third-party.

*Please make sure to follow every step as it will make the lives
of the Python developers much easier!!!*

.. contents::

Steps to File a Bug Report
///////////////////////////////////////////////////////////

Get a SourceForge account
=======================================

In order to file a bug report, you must have an account_ on
SourceForge_.  We realize some people would like to have anonymous
bug reporting for various reasons (anonymity, ease or reporting,
etc.).  But the Python developers made the decision to turn off
anonymous posting so as to make sure you are notified by email when
any action is taken on your report.  This can be very important if a
Python developer needs more information from you about the bug.


Start a new bug
=======================================

You must be logged into SourceForge to file a bug!  See `Get a
SourceForge account`_ if you do not have one.

Go to the `SourceForge bug page`_ to start a new bug report.  There
you will find a link called `Submit New`_.  Click on it and it will
allow you to fill out a new bug report.

Once you click on the link, you are presented with a page that has
several fields for you to fill in.  Here is what to do for each field:

* Private
    Leave this unchecked.
* Category
    Set this to the area that the bug is related to (e.g.,
    documentation, build, etc.).
* Group
    Usually this is set to the major.minor version of Python that you
    found the bug in.
* Summary
    A one-liner describing the problem so as to make it easy for
    developers to spot whether they have the expertise needed to work
    on the bug; it also ends up being displayed as the title on index
    and search pages.
* Detailed Description
    Following sections of this document discuss what should go in
    here.
* Upload and Attach a File
    If you are going to upload a file, either type in the path to the
    file or click the ``Browse...`` button to find the file.
* File Description
    A one-liner describing the file (e.g., how it is different from
    previously uploaded files); no date info is needed since the
    upload is timestamped.


Specify the Python version
=======================================

It is important that we have the most accurate version number of the
interpreter you are using in order to best diagnose the issue.  There
are two ways to get us the version information.

If you can run your Python interpreter, execute the following lines at
at a shell prompt and paste the result into the
``Detailed Description`` field of the bug report::

    python -c "import sys; print sys.version"

If you are running a version of Python older than 2.5 and are working
from a source checkout of Python, the please also report the
Subversion revision number for the root of your checkout::

    svnversion .

If your bug is preventing you from running the interpreter, execute
Python with the ``-V`` command-line flag and paste the output::

    python -V


Special settings for your Python interpreter
============================================

Sometimes your environment influences a bug and thus needs to be
reported to help find the problem.  This means we need to have
reported:

* Operating System
* Environment Variables
    + ``PYTHONSTARTUP``
        If this is set and might be causing the issue, please either
        upload the file or state what it does.
    + ``PYTHONCASEOK``
        If your bug is on Windows and involves importing, please
        report if this environment variable is set or not.
* ``site-packages``
    If you have any third-party packages installed that may be
    contributing to the bug, please report those.
* Custom Patches
    Any differences between your code and the code the Python
    developers work off of needs to be reported.


Sample code to reproduce bug
========================================

If you can, please upload a file the demonstrates the bug.  The more
succinct the better!


Submit!
========================================

At this point you should have a detailed bug report for developers to
work off of.  Click the ``Submit`` button and read on to see what you
should do after the bug is reported.


Respond to requests from developers
========================================

No matter how detailed the bug report, there is always the chance
that a developer will need more information to fix a bug.  Please be
prompt in replying to requests for information by submitting a reply
on the bug report.

You may be asked to test out a patch.  It is very important that you
help with this, especially if the bug is not reproducible by the
developer working on it.


Write a patch!
========================================

If you are so inclined, patches for your own bug reports are always
helpful!  Please make sure to reference the tracker item number in the
patch details.  Also add a follow-up to the bug referencing the
patch.



..  _SourceForge: http://www.sourceforge.net/
..  _SourceForge bug page:
http://sourceforge.net/tracker/?group_id=5470&atid=105470
..  _account: http://sourceforge.net/account/newuser_emailverify.php
..  _Submit New:
http://sourceforge.net/tracker/?func=add&group_id=5470&atid=105470
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.python.org/pipermail/python-dev/attachments/20060824/a246130c/attachment.html