[Python-Dev] first draft of bug guidelines for www.python.org/dev/

[Brett Cannon]

Here is a first stab at writing up guidelines for people to follow
when reporting bug.  If this goes well I will also do ones for
patches, committing, and PEPs.

-Brett

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

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::

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 SourceForge does not support
anonymous reporting.  Plus, by registering, you are notified by email when any
action is been 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:

* Category
    Set this to the area that the bug is related to (e.g.,
documentation, build, etc.).
* Group
    Usually this is set the major.minor version of Python that you
found the bug  in.
* Assigned To
    Leave this alone
* Priority
    Leave this alone
* Summary
    A one-line describing the problem so as to make it easy for
developers to spot whether they have the expertise needed to work on
the bug.
* Detailed Description
   Following sections of this document discuss what should go in here.
* Check to Upload and Attach a File
   If you are going to upload a file, you *must* check this box.
* <File Location Field>
   Click the Browse button to upload any file to accompany your bug
report (usually a succinct way to reproduce the bug).
* File Description
   A one-line describing the file; no date info is needed since the
upload is timestamped.


Specify 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 an
interpreter and paste the result into the ``Detailed Description``
field of the bug report::

  >>> import sys
  >>> print sys.version

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

  python/trunk$ svnversion .

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

  python/trunk$ 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 andy 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!  And please do not forget to check the upload
checkbox in the bug report.


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 off-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 # in the
patch details.



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